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Read This First 


This manual is divided into two independent parts. You should only use 
one of the parts. 


If your installation uses VS, you should read the first part, ‘Part 
I: For the VS User‘. This part is written as a supplement to OS/VS and 
DOS/VS_ Assembler Language, Order No. GC33-4010, which you must use in 
conjunction with this supplement. Further instructions on how to use 
this supplement are contained in the Preface, which you should read to 
be able to use this supplement correctly. 


If your installation uses OS/MFT or OS/MVT, you should read the 
second part, ‘Part II: For the MFT or MVT User’. This part is written 
as a supplement to OS Assembler Lanquage, Order No. GC28-6514, which you 
must use in conjunction with this supplement. Further instructions on 
how to use this supplement are contained in the Preface, which you 
should read to be able to use this supplement correctly. 
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Part I: For the VS User 


Preface 


Purpose and Subject of This Part 


This part is a supplement to the OS/VS and DOS/VS Assembler Language 
manual. That manual describes the language supported by the OS/VS 


Assembler, which is a subset of the language supported by Assembler H. 
This supplement defines the differences between the two languages; 
together the two manuals give you the information you need to write 
instructions that can be assembled by Assembler H. 


Who This Part Is For 


This part has the same audience as defined for the parent manual. The 
knowledge that the reader is assumed to have is defined in that manual. 


How to Use This Part 


First read the parent manual in the section relevant to your enquiries. 
Then check the table of contents in this supplement for the identical 
section heading. If listed, this supplement contains a section on the 
subject. The relevant section describes the differences between the 
language supported by the OS/VS Assembler and the language supported by 
Assembler H. 


Organization of This Part 


This supplement has exactly the same organization as the parent manual: 
chapter and section headings are the same, but only those chapters and 
sections which reflect differences between the two languages are 
included in the supplement. Chapter and section headings that are common 
to both the parent manual and the supplement are underlined in the table 
of contents in this supplement. 


Bibliography 

OS/VS_and DOS/jS Assembler Lanquage, GC33-4010. This manual must be 
used with the supplement. 

OS Assembler H General Information Manual, GC26-3758. This manual gives 


general information about Assembler H, describing the language and 
facilities of the program, and comparing it with the OS/VS Assembler. 
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Section B: Coding Conventions 


Bl — Coding Specifications 


B1A ~- STATEMENT FIELD BOUNDARIES 





The Identification-Sequence Field 


COLUMNS CHECKED BY ISEO =: The columns checked by the ISEQ facility are 
not restricted to columns 73 through 80, or by the boundaries determined 
by any ICTL instruction. The columns specified in the ISEQ instruction 
can be anywhere on the input cards; they can also coincide with columns 
that are occupied by the instruction field. 


B1B -- CONTINUATION LINES 


NORMAL STATEMENT FORMAT: Nine continuation lines are allowed. Thus, a 
Single assembler language statement can occupy up to ten lines. 


ALTERNATE STATEMENT FORMAT : The alternate statement format, which 
allows as many continuation lines as are needed, can be used for the 
following instructions: 





° the prototype statement of a macro definition 

e the macro pueeruceien statement 

e the AGO conditional assembly statement 

e the AIF conditional assembly statement 

© the GBLA, GBLB, and GBLC conditional assembly statements 
e the LCLA, LCLB, and LCLC conditional assembly statements. 
e the SETA, SETB, and SETC conditional assembly statements 
Examples of the alternate statement eornat for each of these 


instructions are given in the context where the individual instruction 
is described. 
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Section C: Assembler Language Structure | 


C4 - Terms | ; 


C4A ~- SYMBOLS 


Specifications 


ORDINARY SYMBOLS: The format of an ordinary symbol is: 


alphabetic character — 


0—62 alphameric characters 
ORbDINARYSYMBOL! 


examples: ORDSYM#435A 
K4 : 


B49467LITTLENAIL 


VARIABLE SYMBOLS: The format of a variable symbol is: 


ampersand 
se alphabetic character 
| O—61 alphameric characters 
EVA RIABLES YMBOL 


examples: & VARY INGSYMABC 
&F346944 
&@ME 


SEQUENCE SYMBOLS: The format of a sequence symbol is: 


period 
alphabetic character 
O—61 alphameric characters 





~> Oo EQUENCES YMBOL 


examples: » BLABELO4 
#359 
 .BRANCHTOMEFIRST 


Restrictions on Symbols 


USE OF DUPLICATE SYMBOL IN NAME FIELD OF CERTAIN INSTRUCTIONS: The 
symbol in the name field of a LOCTR instruction can be the same as the 
name of a previous START, CSECT, DSECT, COM, or LOCTR instruction. It 
identifies the resumption of the location counter specified by the name 
field. 


PREVIOUS DEFINITION NOT REQUIRED: Previous definition is not required 
for symbols in the following operand entries: 


EQU (first operand) 

CNOP 

ORG 

DC and DS’) (in duplication factor and modifier expressions) 


C4B ~- LOCATION COUNTER REFERENCE 


MULTIPLE LOCATION COUNTERS: When using Assembler H, you can specify 
multiple location counters for your control sections. See "E2C -- 
Location Counter Setting" 


C4D -- OTHER ATTRIBUTE REFERENCES 


ADDITIONAL ATTRIBUTE AVAILABLE: When usSing Assemblér H there is one 
attribute additional to the six attributes available when using the 
OS/VS Assembler. The additional attribute is the defined (D') attribute 
(see “L1B -- Data Attributes"). 
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Section E: Program Sectioning 


El - The Source Module _ 


EIA -- THE COPY INSTRUCTION 


NESTED COPY INSTRUCTIONS: Copied code may contain other COPY | 
statements. The OS/VS Assembler allows up to five levels of nested COPY 
instructions. The Assembler H has no restrictions on the nesting of 
COPY statements. 


The COPY nesting must not be recursive. Thus, if the statement “COPY A" 
is coded and A contains a statement “COPY B", B must not contain a 
statement “COPY A". | 


E2 - General Information About Control Sections 


E2C -- LOCATION COUNTER SETTING 


USE OF MULTIPLE LOCATION COUNTERS: Assembler H allows you to use | 
multiple location counters for each individual control section. You use 
the LOCTR instruction (whose format and specifications are described 
under “E3E - The LOCTR Instruction") to assign different location 
counters to different parts of a control section. The assembler will 
then rearrange and assemble the coding together according to the 
different location counters you have specified: all coding using the 
first location counter will be assembled together, then the coding using 
the second location counter will be assembled together, etc. 


A practical use of multiple location counters is illustrated below. 
There, the programmer has interspersed executable instructions and data 
areas throughout the coding in their logical sequence, each group of 
instructions. preceded by a LOCTR instruction identifying the location 
counter under which it is to be assembled. The assembler will rearrange 
the control section so that the executable instructions are grouped 
together and the data areas together. 


SOURCE MODULE OBJECT MODULE 


(shown in source code format) 


E2y1L5 





controlled 












INST ces —e INST,12 by INST 
, location 

USING INST,12 CODE ,X'03!' | counter 

. NEWCARD 
DATA  LOCTR cone) 
INPUTAREA DS 0CL80 enon 
CODE DS CL1 | et 

e “INPUTAREA DS OCL8 0 - controlled 
INST LOCTR i” CODE DS CL1 by DATA 

T™ CODE,X'03' . location 

BM | NEWCARD VALL DC F'S6' counter 

; VAL2 DC F'84! 
DATA  LOCTR 
VALL DC F'S6! 
VAL2 DC F'84! 

; control 
NEXT  CSECT or 

NEXT 


E2G -- EXTERNAL SYMBOL DICTIONARY ENTRIES 





LIMITS TO THE NUMBER OF ESD ENTRIES IN A MODULE: There is no limit to 
the number of individual control sections and external symbols that can 


be defined in a source module. 


E3 - Defining a Control Section 


E3A -- THE START INSTRUCTION 





Specifications 


EXPRESSION ALLOWED IN OPERAND: The operand of a START instruction can 
be an absolute expression, provided that any symbols referenced have 
been previously defined. 


E3B -- THE CSECT INSTRUCTION | 


RESUMING AN INTERRUPTED CONTROL SECTION: When an interrupted control 


section is resumed using the CSECT instruction, the location counter 
last specified in that control section will be resumed. Consider the 
following coding: 
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ALPHA — START 
BALR 12,0 
‘USING 
BETA LOCTR ! 


NEWSECT CSECT 





_ NEWSECT 


ALPHA CSECT 





this part is assembled using 
the BETA location counter 


For further information on the use of multiple location counters, refer 
to “E3E -- The LOCTR Instruction". 


E3C -~ THE DSECT INSTRUCTION 


RESUMING AN INTERRUPTED DUMMY CONTROL SECTION: When an interrupted 
dummy control section is resumed using the DSECT instruction, the 
location counter last specified in that control section will be resumed. 


E3D -~ THE COM INSTRUCTION 


RESUMING AN INTERRUPTED COMMON CONTROL SECTION: When an interrupted 
common control section is resumed using the COM instruction, the 
location counter last specified in that control section will be resumed. 


E3E ~~ THE LOCTR INSTRUCTION 


Purpose 


The LOCTR instruction allows you to specify multiple location counters 
within a control section. The assembler assigns consecutive addresses 
to the segments of code using one location counter before it assigns 
addresses to segments of coding using the next location counter. By 
using the LOCTR instruction, you can code your control section ina 
logical order. For example, you can code work areas and data constants 
within the section of code using them without having to branch around 
them. The concept of multiple location counters is described more fully 
under “E2C - Location Counter Setting". | 


Specifications 


The LOCTR instruction has the following format: 


Bo ae en ee eee WS a etre ge ee ap ge Te ne GR ee paged et VS nae eas ae q 
| Name | Operation | Operand { 
| | | | 
}------------------- $------- ~---}----------------- ~---------- { 
{A variable or | LOCTR | Blank [ 
|ordinary symbol | | [ 
| | | | 
Mes Se Sl ee ea Soca a as Oh i ass eas ced pc oc aa ee sh si ca sci a co Sse a i is Ct lees a ic el es te Sais a ek "Gl er j 

@ The LOCTR instruction defines a location counter SN CSECT 

2] Or resumes a previously defined location counter. LR - 42.15 

. , a 


. 7 oe USING A,12 
A location counter remains in use until it is inter- 


rupted by a LOCTR, CSECT, DSECT, or COM ‘ 
instruction. LOCTR 


B 
1 a fie 
The first location counter of a control section is a LOCTR © 


defined by the name of the START, CSECT, 





DSECT, or COM instruction defining the section. Q ° 

4B LOCTR 
A LOCTR instruction with the same name as a @ ° 

> | 


5] control section resumes the first location counter rN LOCTR 


of that section. 4) 
4 


A LOCTR instruction with the same name as a Beet: DeEet 


A, 


AN 


LOCTR instruction in a previous control section 
6 | causes that control section to be resumed using Cc LOCTR 
the location counter specified. 


END 


A control section cannot have the same name as a previous LOCTR 
instruction. A LOCTR instruction placed before the first control 
section definition will initiate an unnamed control section before the 
LOCTR instruction is processed. 


The length attribute of a LOCTR name is 1. 
LOCTR instructions do not force alignment; code running under a 
location counter other than the first location counter of a control 


section will be assembled starting at the next available byte after the 
previous segment. 


ES - Defining an External Dummy Section 


ESA -- THE DXD INSTRUCTION 


ENTRY IN THE EXTERNAL SYMBOL DICTIONARY: An external dummy section 
identified by a DXD instruction will not generate an entry in the 
external symbol dictionary (ESD) unless it is referenced by a Q-type 
address constant. | 
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Section F: Addressing 


F2 - Addressing Between Source Modules: Symbolic Linkage 


NO RESTRICTION ON THE TOTAL NUMBER OF EXTERNAL SYMBOLS: There is no 
restriction on the number of control sections, external symbols, and 
external dummy sections allowed by the assembler. The maximum number 
depends on main storage available during linkage editing. 


Section G: Symbol and Data Definition 


G2 -- Defining Symbols 
G2A -~- THE EQU INSTRUCTION 
Specifications 


PREVIOUS DEFINITION OF SYMBOLS IN THE FIRST OPERAND NOT REQUIREL: Any 
symbols used in the first operand of the EQU statement need not be 


previously defined. 


COMPLEXLY RELOCATABLE FIRST OPERAND: The first operand of the FQU 
instruction may assume any value allowed for an assembly expression: 
absolute ‘/including negative), relocatable, or complexly relocatable. 


If the expression in the first operand is complexly relocatable, the 
whole expression rather than its value is assigned to the symbol. 
During the evaluation of any expression that includes a complexly 
relocatable symbol, that symbol is replaced by its own defining 
expression. 


Consider the following example, in which A1 and A2 are defined in one 
control section and B1 and B2 in another: 


The first EQU statement assigns a complexly relocatable expression 
(A1+B1) to X. During the evaluation of the expression in the second FOU 
statement, X is replaced by its defining relocatable expression (A1+B1), 
and the assembler evaluates the resulting expression (A1+B1-A2-B2) and 
assigns an absolute value to Y, because the relocatable terms in the 
expression are paired. 


G3 -— Defining Data 
G3B -- GENERAL SPECIFICATIONS FOR CONSTANTS 
Subfield 1: Duplication Factor 


SYMBOLS NEED NOT BE PREVIOUSLY DEFINED: Symbols used in operand 
subfield 1 need not be previously defined. This does not apply to 
literals. 
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Subfield 3: Modifiers 


SYMBOLS NEED NOT BE PREVIOUSLY DEFINED: Symbols used in operand 
subfield 3 need not be rreviously defined. This does not apply to 
literals. 


G3M_-- THE Q-TYPE ADDRESS CONSTANT - , wed 


> 


PREVIOUS DEFINITION OF REFERENCED NAMES NOT REQUIRED: The DXD or DSECT 
names referenced in the Q-type address constant need not be previously 


dersned: 
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Section H: Controlling the Assembler Program 


H] - Structuring a Program 


H1A -- THE ORG INSTRUCTION 


RESTRICTION ON ORG WHEN THE LOCTR INSTRUCTION IS USED: If you specify 
multiple location counters with the LOCTR instruction, the ORG 
instruction can alter only the location counter in use when the 
instruction appears. Thus you cannot control the structure of the whole 
control section using ORG, but only the part that is controlled by the 
current location counter. 


Specifications 


PREVIOUS DEFINITION OF OPERANDS NOT REQUIRED: In general, symbols used 
in the operand field need not have been previously defined. However, 
the simply relocatable component of the expression (that is, the 
unpaired relocatable term) must have been previously defined or be 
equated to a previously defined value. 


MULTIPLE LOCATION COUNTERS: ORG changes the value of the current 
location counter only. Therefore, it cannot reference a location 
outside the current location counter, even though that location may 
belong to the same contrcl section. 


H1C ~- THE CNOP INSTRUCTION 


PREVIOUS DEFINITION OF SYMBOLS NOT REQUIRED: Symbols appearing in the 
operand field of CNOP instructions need not be previously defined. 


H2 - Determining Statement Format and Sequence 


H2B -- THE ISEQ INSTRUCTION 


WHAT COLUMNS CAN BE SEQUENCE CHECKED?: The columns to be sequence 
checked by the ISEQ facility can be anywhere on the cards in the input. 
Thus they can also be between the begin and end columns. 
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H5 -- Redefining Symbolic Operation Codes 


HSA ~- THE OPSYN INSTRUCTION 





PLACEMENT OF OPSYN STATEMENTS: The OPSYN instruction can be coded 
anywhere in the program to redefine an operation code. 


REDEFINING CONDITIONAL ASSEMBLY INSTRUCTIONS: A redefinition of a 
conditional assembly Operation code will have an effect only on macro 
definitions appearing after the OPSYN instruction. Thus, the new 
definition is not valid during the processing of subsequent macro 
instructions calling a. macro that was defined prior to the OPSYN 
statement. | | 


Any OPSYN statement redefining the operation code of an instruction 
generated from. a macro instruction will, however, be valid, even if the 
definition of the macro was made prior to the OPSYN statement. The 
following example illustrates this difference between conditional 
assembly instructions and model statements within macro instructions. 


macro header _ 
macro prototype 





macro trailer 


AIF 3 : assign AGO properties to AIF _ 
MVC | assign MVI properties to MVC — 


macro call 
evaluated as AIF instruction 
generated AIFs not printed] 
+ nee evaluated as MVI instruction 


Open code started at this point 
evaluated as AGO instruction 
evaluated as MVI instruction 


AIF and MVC instructions are used in a macro definition. OPSYN 
instructions are used to assign the properties of AGO to AIF and to 
assign the properties of MVI to MVC, after the macro definition has been 
edited. In subsequent calls to that macro, AIF is still defined as an 
AIF Operation while MVC is treated as an MVI operation. In open code 
following the OPSYN instructions, the operations of both instructions 
are derived from their new definitions. If the macro is redefined, 
either by means of a loop to a point before the macro definition or by a 
subsequent macro definition defining the same macro, the new definitions 
of AIF and MVC cree is, AGO and MVI) will be fixed for future 
expansions. | | : | 
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Section J: The Macro Definition 


Jl -- Using a Macro Definition 


J1B -- SPECIFICATIONS 


Where to Define a Macro in a Source Module 


MACRO DEFINITIONS NEED NOT APPEAR AT THE BEGINNING: Macro definitions 
can appear anywhere in a source module. ‘They remain in effect for the 
rest of your source module or until another macro definition defining a 
Macro with the same operation code is encountered. Thus, you can 
redefine a macro at any point in your program. The new definition will 
be used for all subsequent calls to the macro in the program. 


NESTED MACRO DEFINITIONS: Macro definitions can also appear inside 
other macro definitions. There is no limit to the levels of macro 
definitions permitted. 


The assembler does not process inner macro definitions until it finds 
the definition during the processing of a macro instruction calling the 
outer macro. 


Consider the following example: 


CoN es er re eae fog oe sie be) ee oe re re i ee ee ey 
| Name [| Operation | Operand | Comments | 
| | | | [ 
}------- $-—< $-- seat aaettaaeaeateaeenemeenearenmtatneanetetetanatemeteteentes { 
| | MACRO | _|macro header for outer macro |] 
| | OUTER | 6A, &C= {macro prototype | 
| | AIF [| ("6C* EQ *").A | H 
| | MACRO | jmacro header for inner macro {| 
{ | INNER | [macro prototype { 
| |. | | [ 
lie | . . 
| | MEND | |macro trailer for inner macro | 
{.A | ANOP | | i 
; | . 
{ | MEND | {macro trailer for outer macro | 
| | | | [ 
Get eacs: year Drea omere ote Sey lee as Spee aera aca ag a i as ee et ~J 


The assembler does not process the macro definition for INNER until 
OUTER is called with a value for &C other than a null string. 
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J2 -- Parts of a Macro Definition 


J2C -- THE MACRO PROTOTYPE STATEMENT: CODING 


Specifications 


INSERTING COMMENT STATEMENTS BEFORE THE PROTOTYPF: The Assembler H 
allows internal comments statements between the macro header and the 
macro prototype. Internal comments statements are listed only with the 
macro definition. 


MAXIMUM NUMBER OF OPERANDS: The maximum number of symbolic parameters 
allowed by Assembler H is 240. 





J2D -~ THE MACRO PROTOTYPE STATEMENT: ENTRIES 


The Operation Entry 


OPERATION ENTRY PREVIOUSLY DEFINED: Any operation code can be specified 
in the prototype operation field. If the entry is the same as an 
assembler or machine operation code, the new definition overrides the 
previous use of the symbol. The same is true if the specified operation 
code has been defined earlier in the program as a macro, or is the 
operation code of a library macro. 


The Operand Entry 


MAXIMUM NUMBER OF OPERANDS: The maximum number of symbolic parameters 
that can be specified in the operand field is 240. 


J2E -- THE BODY OF A MACRO DEFINITION 
Specifications 


NESTED MACRO DEFINITIONS: You can include macro definitions in the body 
of a macro definition. This is explained under "J1 -- Using a Macro 
Definition". 
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J3 - Symbolic Parameters 


General Specifications 


FORMAT: The format of a symbolic parameter is: 


ampersand 
alphabetic character 
O-—61 alphameric characters 





& SY MBOLICPARAMER 


J4 — Model Statements 


J4B -- SPECIFICATIONS 


Format of Model Statements 


LISTING OF GENERATED FIELDS: The different fields in a macro-generated 
Statement or a statement generated in open code appear in the listing in 
the same column as they are coded in the model statement, with the 
following exceptions: | 


If the substituted value in the name or operation field is too large 
for the space available, the next field will be moved to the right 
with one blank separating the fields. ; 


If the substituted value in the operand field causes the remarks 
field to be displaced, the remarks field is written on the next 
line, starting in the column where it is coded in the model 
statement. 


If the value substituted in the operation field of a macro-generated 
statement contains leading blanks, the blanks are ignored. 


If the value substituted in the operation field of a model statement 
in open code contains leading blanks, the blanks wili be used to 
move the field to the right. 


If the value substituted in the operand field contains leading 
blanks, the blanks will be used to move the field to the right. 


If the value substituted contains trailing blanks, the blanks are 
ignored. 
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Rules for Model Statement Fields 


SPECIFYING OPSYN AS A MODEL STATEMENT: OPSYN is allowed in the _ 
operation field of a model statement. Substitution is allowed in the 
name, Operation, and operand fields of the instruction. 


J5 -- Processing Statements 


J5F -~ THE AREAD INSTRUCTION 





Purpose 


The AREAD instruction allows you to assign to a SETC symbol the 
character string value of a card that is placed immediately after a 
macro instruction. The AREAD facility functions in much the same way as 
symbolic parameters, but instead of supplying your input to macro 
processing as part of the macro instruction, you add,the values in the 
form of whole 80-character input records that follow immediately after 
the macro instruction. Any number of successive cards can be read into 
the macro for processing. 


Specifications 


The AREAD instruction can only be used inside macro definitions. Its 
format is: 


ee a ee ee pe eg np ee Mee ey ee ee gees Cee ee cg q 
| Name | Operation | Operand [ 
| | | | 
}~------------------ }------~----}+--------------------------- { 
[Any SETC | AREAD | fNostier ] { 
Je cai { | NOPRINT [ 
Cs sen nee eteeeaeo was ye arene ea eee ee as hee J 


The SETC symbol in the name field may be subscripted. When the assembler 
encounters the AREAD statement during the processing of a macro 
instruction, it reads the source card following the macro ‘instruction 
and assigns an 80-character string to the SETC symbol in the name field. 
In the case of nested macros, it reads the card following the outermost 
macro instruction. 


If no operand is specified, the card to be read by AREAD is printed in 
the listing and assigned a statement number. If NOSTMT is specified in 
the operand, the card is printed, but not given any statement number. 
If NOPRINT is specified, the card does not appear in the listing and no 
statement number is assigned to it. 


Repeated AREAD statements read successive cards. 


The records read by the AREAD instruction can be in code brought in with 
the COPY instruction, if the macro instruction appears in such code. If 


no more records exist in the code brought in by the COPY instruction, 


subsequent cards are read from the ordinary input stream. 
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Example: 


“4 
{ 
{ 
{ 
t 
{ 
1 
{ 
{ 
{ 
! 
{ 
t 
i 
{ 
t 
{ 
{ 
t 
{ 
i 
! 
1 
{ 
{ 
{ 
1 
' 
} 
{ 
| 
{ 
{ 
j 
f 
{ 
i 
( 
{ 
j 
f 
{ 
| 
{ 
{ 
( 
{ 
! 
! 
{ 
| 
{ 
{ 
! 
{ 
t 
t 
{ 
i 
! 
i 
! 
i 
{ 
' 
{ 
! 
{ 
i 
i 
{ 

ei 


EVAL AREAD 
EVAL1 AREAD 


MEND 
CSECT 
MAC1 
THIS IS THE CARD TO BE PROCESSED FIRST 
THIS IS THE SECOND CARD FOR THE SECOND AREAD 


= ee oe oe 0 ee ee ee ee ee ee ee ewe ee ee 
1 aR ea ny SET OPI VED PEN ER CON eg NOR R  Peam 


J6 - Comments Statements 


J6A -- INTERNAL MACRO COMMENTS STATEMENTS 


PLACEMENT OF COMMENTS STATEMENTS: The Assembler H allows internal 
comments statements between the macro header and the prototype 
statement. 


JZ - System Variable Symbols 


ADDITIONAL SYSTEM VARIABLE SYMBOL AVAILABLE: Assembler H supports the 
System variable symbol &SYSLOC which gives you the name of the location 
counter in effect when the macro instruction appears. See below under 
“J7G -- &SYSLOC". 


J7C -~ &SYSLIST 


USING MORE THAN TWO SUBSCRIPTS: When referring to multilevel sublists 
in operands of macro instructions, reference to elements of inner 
sublists can be made using the appropriate number of subscripts for 
SSYSLIST. See examples under “K4& - Sublists in Operands”. 


J7E -- &SYSPARM 


DEFAULT VALUE FOR &SYSPARM: If &SYSPARM is omitted in the PARM field of 
the EXEC statement that invokes the assembler, the system parameter is 
assigned the value that was specified when the Assembler H was generated 
(added to your system). | 
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J7G -- &SYSLOC 


Purpose 


You can use &SYSLOC in a macro definition to generate the name of the 
location counter currently in effect. If you have not coded a LOCTR 
instruction between the macro instruction and the preceding START, . 
CSECT, DSECT, or COM instruction, the value of &SYSLOC is the same as 
the value of &SYSECT. 


Specifications 


The assembler assigns to the system variable symbol &SYSLOC a local 
read-only value each time a macro definition containing it is called. 
The value assigned is the symbol representing the name of the regen 
counter in use at the point where the macro is called. 


ESYSLOC can only be used in macro definitions. 
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Section K: The Macro Instruction 


Kl] — Using a Macro Instruction 


K1B ~~ SPECIFICATIONS 


PLACEMENT OF MACRO INSTRUCTIONS: A macro instruction can be coded 
anywhere in your program, if the assembler finds its definition either 
in a macro library, or in the source module before it finds the macro 
instruction. 


K2 -- Entries for Fields 


K2B -- THE OPERATION ENTRY 


GENERATED MACRO INSTRUCTION: You can code a variable symbol in the 
operation field of a macro instruction if the value of the variable 
symbol specifies the operation code of a library or source macro that 
has been previously defined. Thus, if MAC1 has been defined as a macro, 
you can use the following statements to call it: 


&CALL SETC *MAC 1° 
&CALL 


K4 - Sublists in Operands 


MULTILEVEL SUBLISTS: You can specify multilevel sublists (sublists 
within sublists) in macro operands. The depth of this nesting is 
limited only by the constraint that the total operand length must not 
exceed 255 characters. Inner elements of the sublists are referenced 
using additional subscripts on symbolic parameters or on &SYSLIST. 


N*'&SYSLIST with an n-element subscript array gives the number of 
operands in the indicated n-th level sublist. The number attribute (N‘) 
and a parameter name with an n-element subscript array gives the number 
of operands in the indicated (n+1)th level sublist. 
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Example: If &P is the first positional parameter and the value assigned 


in a macro instruction is (A, (B, (C)) ,D) then: 


oe ee ae em ee ew ome ee oe OF 


&P _=§SYSLIST (1) = (A, (B, (C)) ,D) 
&P (1) | =§ SYSLIST (1, 1) = A 

&P (2) =§ SYSLIST (1, 2) =  (B, (C)) 

&P (2, 1) =§ SYSLIST (1, 2, 1) = B 

&P (2, 2) =§ SYSLIST (1, 2, 2) = (C) 

&P (2,2, 1) =ESYSLIST(1,2,2,1) = Cc 

&P (2,2, 2) =§SYSLIST(1,2,2,2)  =null 

&P (3) | =§SYSLIST (1,3) | = D. 
IN°&P (2,2) = «= =N"ESYSLIST(1,2,2) = 

[N° &P (2) =N'&SYSLIST (1, 2) = 

IN &P (3) =N'&SYSLIST (1, 3) = 

IN‘ EP =N*§SYSLIST (1) =3 

Oa cs sans ss sn te ck ces an ts enn: ces ins Ses ae ce cs taco ce se Sa aca a cee ge ec a a cas gn ch cs as et meta ses eos ele we an ai ts 


=“ 


PASSING SUBLISTS TO INNER MACRO INSTRUCTIONS: You can pass a suboperand 


of an outer macro instruction sublist as a sublist to an inner macro 


instruction. 


KS — Values in Operands — 
Specifications 


EQUAL SIGN IN POSITIONAL OPERANDS: The assembler issues a warning 


message for a positional operand containing an equal sign, ifthe 
operand resembles a keyword operand. Thus, if we assume that the 
following is the prototype of a macro definition: 
MAC 1 &F 
the following macro instruction would generate a warning message: 
MAC1 K=L (K is a valid keyword) 
while the following macro instruction would not: 


MAC1 2+2=4 (2+2 is not a valid keyword) 
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Section L: The Conditional Assembly Language 


Ll —- Elements and Functions 


L1A ~~ SET SYMBOLS 


Specifications 
FORMAT: The format of a SET symbol is: 


ampersand 


alphabetic character 
ZL O—61 alphameric characters 
Biste TS YMBOL : 


examples:  &ARITHMETICVALUE439 
& BOOLEANFORCOMPARISON37 
& CHARACTERSTRINGFORA35 


IMPLICIT DECLARATION: Local SET symbols need not be declared by 
explicit declarations. The assembler considers any undeclared variable 
symbol found in the name field of a SETx instruction as a local SET 


symbol. 


Subscripted SET Symbols -- Specifications 


DIMENSION OF SUBSCRIPTED SET SYMBOLS: The dimension (the maximum value 
of the subscript) of a subscripted SET symbol is not determined by the 
explicit or implicit declaration of the symbol. The dimension specified 
can be exceeded in subsequent SETx instructions. 


Created SET Symbols 


Assembler H can create SET symbols during conditional assembly 
processing from other variable symbols and character strings. A SET 
symbol thus created has the form & (e), where “e“ represents one Or more 
of the following: 

e Variable symbols, optionally subscripted. 

e Strings of alphameric characters. 


® Other created SET symbols. 
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After substitution and concatenation "e"“ must consist of a string of up 
to 62 alphameric characters, the first of which is alphabetic. The 
assembler will consider the preceding ampersand and this string as the 
name of a SET variable. 


You can use created SET symbols wherever ordinary SET Symbols are 
permitted, including declarations. You can also nest them in other 
created SET symbols. Consider the following example: aah 


CS ee oe ee Qe ee ee 1 

| Name | Operation | Operand | 

| | | | 
}------------------- $------~--- ~}-----------~----------------| 

| ABC (1) | SETC LeMKT*, *° 27" 5." $5" { 

ie ee ad ast eee a Ba 
Let &(e) equal & (SABC (&1) QUA&I) . 

iain a: gaa ania aaa rp ce ge ee re ge ee ee eee, 1 
| é1 | SABC (61) {Created SET Symbol ‘1Comment | 
| | | | | 
}------- +-----+----- }------------------- }------------------------------ { 
11 [MKT | EMKTOUA1 | Valid | 
12 | 27 | &27QUA2 | [Invalid: first ; 
| | | {character after 
| | | |& not alphabetic l 
13 1$5 | &$5QUA3 | {Valid | | 
14 | | SQUA4 {| Valid | 
bret ts eae eee eae ped bec oes eeee  e  e  e e e J 


The created SET symbol can be thought of as a form of indirect 
addressing. With nested created SET symbols, you can get this kind of 
indirect addressing to any level. 


In another sense, created SET symbols offer an associative memory 
facility. For example, a symbol table of numeric attributes can be | 
referenced by an expression of the form & (&SYM) (€&1I) to veer the “Ith* 
attribute of the symbol name in &SYM. 


Created SET symbols also enable you to get some of the effect of 
multiply-dimensioned arrays by creating a separate name for each element 
of the array. For example, a three-dimensional array of the form 

&X (61,6),&K) could be addressed as & (X&1.$&J.$&K). Thus “&X (2,3,4)" 
would be represented by &X2$3$4. The “$"s guarantee that &X (2,33,55) 
and 6X (23,35,5) are unique: 


6X (2,33,55) becomes &X2 $33 $55 
6X (23,35,5) becomes 6X23$35$5 


LIB -~ DATA ATTRIBUTES 
What Attributes Are 


NUMBER OF ATTRIBUTES AVAILABLE: Under the Assembler H there are seven 
attributes available. In addition to the six attributes available under 
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the OS/VS Assembler, the Assembler H also supports the defined (D°) 
attribute described below. 


Purpose 


THE DEFINED ATTRIBUTE: The defined attribute determines whether a 
symbol has been defined prior to the point where the attribute reference 
is coded. 


Specifications 


COMBINATION WITH SYMBOLS: The following table shows the seven kinds of 
attributes, identifying the types of symbols they can be combined with. 


ATTRIBUTES SPECIFIED 


| SYMBOLS Type Length a oo 
SPECIFIED | T’ L’ 
IN THE OPEN CODE 
Ordinary Symbols 
SET ee SETC aaa SETC only SETC only SETC lhaienas 
5 ee 
System Variable Symbols: 
&SYSPARM 
&SYSDATE 
&SYSTIME 
IN MACRO DEFINITIONS 
‘Ordinary Symbols YES YES YES YES YES 
SET Symbols SETC only |} SETC only SETC only SETC only 
=a ae 


| symbole Premetn — Parameters 


| System Variable Symbols: 
&SYSLIST 
&SYSECT, &SYSLOC, 
&SYSNDX, &SYSPARM, | YES YES NO NO 
&SYSDATE, &SYSTIME 


REFERENCES TO GENERATED STATEMENTS: You can reference instructions 
generated by conditional assembly substitution or macro expansion with 
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attributes. However, no such reference can be made ner the 


instruction is generated. 


\Q 


THE TYPE ATTRIBUTE (T‘): Because Assembler H allows attribute 
references to statements generated through substitution, certain cases 

where a type attribute of U (Undefined) or M (Macro) is given under the 

OS/VS Assembler, may give a valid type attribute under Assembler H. 

Assembler H allows you to use the type attribute with a SETC symbol if 

the value of the SETC symbol is equal to the name of an instruction that 
can be referenced by the type attribute. 


THE LENGTH ATTRIBUTE (L'): Assembler H allows you to use the length 
attribute with a SETC symbol if the value of the SETC symbol is equal to 
the name of an instruction that can be referenced by the length 
attribute. | 


THE SCALING ATTRIBUTE (S‘): Assembler H allows you to use the scaling 
attribute with a SETC symbol if the value of the SETC symbol is equal to 
the name of an instruction that can be referenced by the scaling 
attribute. 


THE INTEGER ATTRIBUTE (I‘): Assembler H allows you to use the integer 
attribute with a SETC symbol, if the value of the SETC symbol is equal 
to the name of an instruction that can be referenced by the integer 
attribute. 


THE NUMBER ATTRIBUTE (N°) 2) The number attribute, when applied to a 
subscripted SET symbol, is equal to the highest element to which a value 
has been assigned in a SETx instruction. 


For example, if the only references to &A have been 


LCLA €A (100) 
&A (5) SETA 20,,,/0 (See description of extended 
| AIF (6A (20) GT 50) .M SET statements) | 


then N'&A is equal to 8, because &A (8) is asSigned the value 70. 


THE DEFINED ATTRIBUTE (D‘): . The defined attribute indicates whether or 
not the symbol referenced has been defined prior to the attribute 
reference. A symbol is considered as defined if it has been encountered 
in the operand field of an EXTRN or WXTRN statement or in. the name field 
of any other statement. The value of the defined attribute is 1 if the 
symbol has been defined or 0 if the symbol has not been defined. 


The defined attribute can reference all symbols that can be referenced 
by the scaling (S‘) attribute. 


The following is an example of how you can use the defined attribute: 


AIF (D' A) . AROUND 
- AROUND ANOP | 
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In this example, the statement at A would be assembled, since the branch 
around it would not be taken. However, if by a branch, the same 
statement were processed again, the statement at A would not be 
assembled: 


.UP AIF (D'A) . AROUND 
A LA 1,4 
. AROUND ANOP 

AGO .UP 


You can save assembly time using the defined attribute. Each time the 
assembler finds a reference (attribute or branch) to an undefined 
symbol, it initiates a forward scan until it finds that symbol or 
reaches the END statement. You can use the defined attribute in your 
program to prevent the assembler from making this time-consuming forward 
scan. 


L1C -- SEQUENCE SYMBOLS 


FORMAT: The format of a sequence symbol is: 


period 
alphabetic character 
O—61 alphameric character 





JIlstp QUENCES YMBOL 


example: . BRANCHINGLABEL1L 


L2 -- Declaring SET Symbols 


IMPLICIT DECLARATION: Local SET symbols need not be declared explicitly 
with LCLA, LCLB, or LCLC statements. The assembler considers any 
undeclared variable symbol found in the name field of a SETA, SETB, or 
SETC statement to be a lccal SET symbol. It is given the initial value 
specified in the operand field. If the symbol in the name field is 
subscripted, it is declared as a subscripted SET symbol. 


L2A ~~ THE LCLA, LCLB, AND LCLC INSTRUCTIONS 


specifications 


MULTIPLE DECLARATIONS OF SET SYMBOLS: Multiple LCLx statements can 


declare the same variable symbol if only one declaration for a given 
symbol is encountered during the expansion of a macro. 
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MAXIMUM VALUE OF SET SYMBOL SUBSCRIPT: There is no limit to SET symbol 
dimensioning. The limit specified in the explicit (LCLx) or implicit 
(SETx) declaration can also be exceeded, by subsequent SETx statements. 


ALTERNATE FORMAT FOR LCLX STATEMENTS: The Assembler H permits the 
alternate statement format for LCLx instructions. An example is: 


Statement Field Continuation Indicator 


&LOCALSYMBOLFORDCGEN, : xX 
&COUNTERFORINNERLOOP, Xx 
&COUNTERFOROUTERLOOP, X 
&§ COUNTERFORTRAILINGLOOP 











L2B -~ THE GBLA, GBLB, AND GBLC INSTRUCTIONS 


Specifications 


MULTIPLE DECLARATIONS OF SET SYMBOLS: Multiple GBLx statements can 
declare the same variable symbol if only one declaration for a given 
symbol is encountered during the expansion of a macro. 


MAXIMUM VALUE OF SET SYMBOL SUBSCRIPT: There is no limit on the maximum 
subscript allowed. Also, the limit specified in the global declaration 
(GBLx) can be exceeded. 


ALTERNATE FORMAT FOR GBLX STATEMENTS: The Assembler H permits the 
alternate statement format for GBLx instructions. An example is: 


Statement Field Continuation Indicator 


& GLOBALSYMBOLFORDCGEN, 
ELOOPCONTRLA, 

& VALUEPASSEDTOMACDUFF, 

& VALUERETURNEDFROMMACDUFF 





L3 - Assigning Values to SET Symbols 


Extended SET Statements 





You can assign values to multiple elements in an array of a subscripted 
SET symbol with one single SETx instruction. Such an instruction is 
called an extended SET statement. 
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The format of an extended SETIx statement is: 


rc <> Cub Cem 08s CRD GUD OES ED 8D Oe Ct EP 42 Oe oD ae Om ae ae T ore ce CD ane CP C2 an eo ar anaes 


Se re re ee 1 
[ Name | Operation | Operand | 
| | | | 
}------------------- {----------- }---------------------------- { 
{A subscripted ||SETA joperand1,operand2, [ 
| variable KSETE joperand3,....,operandn | 
[symbol ([SETC | 
Vevseesewec Sea oe eS Me Sears cece Meise csaset Ge are SS ae 4 


The name field specifies the name of the SET symbol and the position in 
the array to which the first value in the operand field is to be 
assigned. The successive operand values are then assigned to the 
successive positions in the array. If an operand is omitted, the 
corresponding element of the array is unchanged. Consider the following 
example: 


ree Se in ee T ee ie ee a ne “T 
[ Name | Operation | Operand | 
| | | 
}-------~----~----~- $----------- {--------------------------- -{ 
| | LCLA | €LIST (50) 
| &LIST (11) | SETA 15,10,,20,25,30 ] 
ei ee y eaeRiaene eee ee as aaa erase eer hae tases aoe at 


Tne first instruction declares &LIST as a subscripted local SETA symbol. 
The second instruction assigns values to certain elements of the array 
SLIST: 





not assigned 


(SES Se en ee haan aaa a etarias aa aa aaa a a a a aa as saa 
| Name {| Operation | Operand i 
| | | | 
~--~------~-------- }-----------}----------------------------f 
| €&LIST (11) | SETA [5 
| &LIST (12) | SETA 110 
| &LIST (14) ? | SETA [20 | 
| LIST (15) | SETA [25 
| &LIST (16) | SETA {30 | 
ea as Se kil de Ss eae a WS as aca caenremeret so tiat ace etaae eet ie ot j 


ALTERNATE STATEMENT FORMAT: You can use the alternate statement format 
for extended SETx statements. The above coding could then be written as 
follows: 3 


. Continuation 
Name Operation Operand Remarks Indicator 
&LIST(11) SETA 5y THIS IS X 

10,, AN ARRAY X 


20,25,30 SPECIFICATION 
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L4 -- Using Expressions _ 


L4A -- ARITHMETIC (SETA) EXPRESSIONS 


SETC VARIABLES IN ARITHMETIC EXPRESSIONS: The Assembler H permits a 


SETC variable to be used as a term in an arithmetic expression if the 
character string value of the variable is a self-defining term. The 
value represented by the string is assigned to the arithmetic term. A 
null string is treated as zero.: The OS/VS Assembler allows SETC 
variables as arithmetic terms only if the value of the variable is a 
decimal self-defining term, not longer than ten characters. 


Examples: 

ee a ee Sa pela cen alread ee q 
l Name | Operation | Operand | 
| | | 

}--------~---------- $----------- }---------------------------- { 
| {| LCL | §C (5) | 
| &C (1) | SETC f*B**101"** ; 
| &C (2) | SETC peceeaere | 
{ &C (3) | SETC [*23° | 
| éA | SETA | &C (1) +&C (2) ~&C (3) * [ 
{SAA | |SETA | hatin ! 
eee eeceeeees Does cpe i scl gees Dn erates ssa Sadar lara aniacueee ores ee 


* (Allowed only by Assembler 4) | 
2 (Allowed by the OS/VS Assembler and Assembler Rh) 


In evaluating the arithmetic expression in the fifth statement, the 
first term (&C(1)) is assigned the binary value 101 (5). To that is 
added the value represented by the EBCDIC character A (hexadecimal C1 
which corresponds to decimal 193). Then the value represented by the 
third term (&C (3)) is subtracted, and the value of &A becomes 

5419 3=-23=175. 


This feature allows you to associate numeric values with EBCLIC or | 
hexadecimal characters to be used in such applications as indexing, code 
conversion, translation, and sorting. 


Assume that &X is a character string with the value ABC. 


aia actaeina sa ee ee ee ee ee re ee re ee eee en 2 
| Name | Operation | Operand | 
| | | : | 
~------------------ }-----------}----------------------------4 
| 62 _ | SETC pPCe etext (t,t test 
| VAL [SETA — { €TRANS (€1I) | | 
(edhcnna ewe oes boot oinwe Loin ca uae ewe wan Geena! 


The first statement sets 6I to C‘A*. The second statement 
extracts the 193rd element of TRANS (C'A® = X*C1* = 193). 
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The following code will convert a hex value in &H into a decimal 
value in &VAL: 


Ce ee a aac are are tse ee eae ey ee aap pteee= =o 
| Name | Operation | Operand [ 
| | | | 
~------~----------- }-----------}-----------------+----------} 
| 6X | SETC P*x'*ene'* | 
| €VAL | SETA [&x 
iE gee pear forte ee ee eee pctare: Bee tae tines ase ee tate ee 5 


An arithmetic expression must not contain two terms in succession; 

however, any term may be preceded by any number of unary operators. 
+&A*-&B is a valid operand for a SETA instruction. The expression 

&SFIELD+- is invalid because it has no final term. 


MAXIMUM SIZE: The maximum number of levels of parentheses allowed in an 
arithmetic expression is 255. 


L4C -- LOGICAL (SETB) EXPRESSIONS 


LIMITATION TO LOGICAL OPERATORS: There is no limit to the level of 
parentheses allowed in logical expressions. 


L6 -- Branching 


L6A -- THE AIF INSTIRUCTION 
Extended AIF Instruction 


The extended AIF instruction allows you to combine several successive 
AIF statements into one statement. The extended AIF instruction has the 
following format: 


ama aaa ats Coo Geeta rae tag er ee —“ 
| Name | Operation | Operand { 
: 
{A sequence [AIF | | (logical expression) .S1, [ 
{symbol or [ | (logical expression) .S2,. { 
{ blank dT J.-.., (logical expression) .Sn| 
| | { | 
ae ae a an en se ne Pe eM oe ee ee eae een a a ao ae ad 


It is exactly equivalent to n successive AIF statements. The branch is 
taken to the first sequence symbol (scanning left to right) whose 
corresponding logical expression is true. If none of the logical 
expressions is true, no branch is taken. 
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('@L'(&C,1) EQ’ gt ).DOLR, ('&L' (&C,1) EQ ' #').POUND, 
("eL'(&C,1) EQ '@').AT,('a&L'(&C,1) EQ '='). EQUAL, 
('gL'(&C,1) EQ '('). LEFTPAR, ('&L' (&C,1) EQ '+') ,PLUS, 
('gL'(&C,1) EQ '-') MINUS | 





This statement looks for the occurrence of a $, #, @, =, (, +, and -, in 
that order; and causes control to branch to .DOLR, .POUND, .AT, .EQUAL, 
-LEFTPAR, .-PLUS, and .MINUS, respectively, if the string being examined 
contains any of these characters. 


THE ALTERNATE STATEMENT FORMAT: The alternate statement format is 
allowed for extended AIF instructions. The format is illustrated by the 
example above. 


L6B -- THE AGO INSTRUCTION 


Computed AGO Instruction 


The computed AGO instruction allows you to make branches according to. 
the value of an arithmetic expression specified in the operand. The 
format of the computed AGO instruction is as follows: 


a ak a ae aaa oo re ee eae ee re ea aoe 
| Name | Operation | Operand : 
}-------------- ~----}-------- Wf ----- == ----------------- { 
{A sequence {| AGO (arithmetic 0S1,-S2,222,-5n | 
| symbol or | jlexpression [ 
laeeaias | { | 
Oa ies ne cet cei eb at is ce a ee ates ae we cee ee ee ee oe ch i ene sem rw at ee cana Se mim in in ice sh sn ce ce is ae as sm i cane B | 


If the arithmetic expression evaluates to k, where k lies between 1 and 
n (inclusive), then the branch is taken to the “k-th” sequence symbol in 
the list. If k is outside that range, no branch is taken. 


In the following example 


control passes to the statement at .THIRD if éI=3. Control passes | 
through to the statement following the AGO if &I is less than 1 Or — 
greater than 4. 


30 


THE ALTERNATE STATEMENT FORMAT: ‘The alternate statement format is 
allowed for computed AGO instructions. The example above could be 


coded: 


Statement Field . Continuation Indicator 


AGO (SI) .FIRST, X 
«SECOND, X 
-THIRD, : xX 
- FOURTH 


L9 -~ Macro Trace Facility 


L9A -~ THE MHELP INSTRUCTION 


Purpose 


The MHELP instruction controls a set of trace and dump facilities. 
Options are selected by an absolute expression in the MHELP operand 
field. MHELP statements can occur anywhere in open code or in macro 
definitions. MHELP options remain in effect until superseded by another 
MHELP statement. 


, 


Specifications 


The format of this instruction is as follows: 


res fe ee ee pe Mee re ea a ee Ree pg ar Ore 1 
| Name | Operation | Operand [ 
| | | 

p---- === -------=- }----------- }----------------- ~---------- 
[A sequence symbol |MHELP [Absolute expression, binary | 
Jor blank | Jor decimal options as | 
| | {discussed below. [ 
I | | 
i] Ee poe eee ens ey reer ne eee Biase cies ie pale Fae ee an OD ny a a rE J 


Macro Call Trace -- Operand=1 


This option provides a one-line trace listing for each macro call, 
giving the name of the called macro, its nested depth, and its &SYSNDX 
value. The trace is provided only upon entry into the macro. No trace 
is provided if error conditions prevent entry into the macro. 


Macro Branch Trace -- Operand=2 


This option provides a one-line trace listing for each AGO and true AIF 
conditional-assembly statement within a macro. It gives the | 
model-statement numbers of the “branched from" and the “branched to" 
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statements, and the name of the macro in which the branch occurs. This 
trace option is suppressed for library macros. | 


Macro AIF Dump -- Operand=4 


This option dumps undimensioned SET symbol values from the macro 
dictionary immediately before each AIF statement that is encountered. 


Macro Exit Dump -- Operand=8 


This option dumps undimensioned SET symbols from the macro dictionary 
upon entering a MEND or a MEXIT statement. 


Macro Entry Dump -- Operand=16 


This option dumps parameter values from the macro dictionary immediatel 
after a macro call is processed. 


Global Suppression -- Operand=32 


This option suppresses global SETI symbols in two preceding options, 
MHELP 4 and MHELP 8. 


MHELP Suppression -- Operand=128 


This option suppresses all currently active MHELP options. 


MHELP Control On &SYSNDX 


The MHELP operand field is actually mapped into a fullword. 
Previously-defined MHELP codes correspond to the fourth byte of this 
fullword. 


&ESYSNDX control is turned on by any bit in the third byte (operand | 
values 256-65535 inclusive). Then, when &SYSNDX (total number of macro 
calls) exceeds the value of the fullword which contains the MHELP 
operand value, control is forced to stay at the open-code level, by in 
effect making every statement in a macro behave like a MEXIT. Open code 
macro calls are honored, but with an immediate exit back to open code. 
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Examples: 


oe a era ace eg a ee eee ee ee ee CS A Fee ee 1 
| | 
| MHELP 256 Limit &SYSNDX to 256. [ 
| MHELP 1 Trace macro calls. ] 
{ MHELP 256+1 Trace calls and limit &SYSNDX to 257. ] 
| MHELP 65536 No effect. No bits in bytes 3,4. { 
| MHELP 65792 Limit &SYSNDX to 65792. [ 
| | 
idiscs sp cloe iy Sh aes ease ees ee ee ee ee ee J 


When the value of &SYSNDX reaches its limit, the message “ACTR EXCEELDEL 
-~ §&SYSNDX" is issued. 


Combining Options 


As shown in the example above, multiple options can be obtained by 
combining the option codes in one MHELP operand. For example, call and 
branch traces can be invoked by MHELP B‘11°', MHELP 2+1, or MHELP 3. 
Substitution by means of variable symbols may also be used. 
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&SYSLIST 17, 19-20 

&SYSLOC 18 

&SYSNDX, MHELP control of 32 
&SYSPARM 17 


Absolute expressions in START 
operand 5 
Address constant 
(see also DC instruction) 
Q-type, referencing external 
dummy section 7 
Addressing between source modules 8 
AGO instruction, computed 30-31 
Alternate statement format 31 
Tracing (see macro branch trace) 
AIF instruction, extended 29-30 
Alternate statements format 30 
Macro AIF dump 32 
Tracing (see macro branch trace) 
Alternate statement format 1 
For AGO instruction 31 
For AIF instruction 30 
For GBLx instruction 26 
For LCLx instruction 26 
For SETx instruction 27 
Arbitrary language input (see AREAD 
instruction) 
AREAD instruction 16-17 
Repeated AREAD instructions 16 
Within code inserted by COPY 16 
Arithmetic expression 
Maximum size 29 
SETC variables in 28-29 
Attributes 22-25 
Combination with symbols 23 
Defined attribute (D') 23, 24-25 
Integer attribute (I') 24 
Length attribute (L') 24 
Number attribute (N') 
For SET symbol 24 
With multilevel sublists 19-20 
References to generated statements 23-24 
Scaling attribute (S') 24 
Type attribute (T') 24 


Character variables used in 
arithmetic expression 28-29 
CNOP instruction 1l 
COM instruction 6 
Comments statements, internal macro 14,17 


Index 


Common control section 
(see COM instruction) 
Complexly relocatable symbols 
in EQU operand 9 
Computed AGO instruction 
(see AGO instruction, computed) 
Constant (see DC instruction) 
Continuation lines | 
Alternate format (see alternate 
statement format) 
Normal format 1 
Control section 
Controlling with the ORG instruction 1l 
Initiating an unnamed with the 
LOCTR instruction 7 
Resuming an interrupted 
Ordinary control section 5-6 
Common control section 6 
Dummy control section 6 
Using multiple location counters in 4-5 
COPY instruction 
Nested 4 
With AREAD 16 | 
Created SET symbol 21-22 


CSECT instruction (see control section) 


DC instruction 
Symbols in subfield 1 9 
Symbols in subfield 3 10 
Declaration of SET symbols 25-26 
Alternate format for 26 
Implicit declaration 25 
Maximum value of SET symbol 
subscript 26 
Multiple declarations 25,26 
Defined attribute 23, 24-25 
Definition of SET symbols 
(see declaration of SET symbols) 
Dimension of SET symbol, maximum 26 
DS instruction 
Symbols in subfield l1 9 
Symbols in subfield 3 10 
DSECT instruction 6 
Dummy control section (see 
DSECT instruction 
DXD instruction 
ESD entry for 7 
Name in Q-type address constant 7 


EQU instruction 
Complexly relocatable first operand 9 
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- Symbols in first operand 9 
Equal sign in macro instruction 
positional operand 20 
ESD (see external symbol dictionary) 
Exponent modifier (see modifiers) 
Expression 
Arithmetic (see arithmetic expression) 
In EQU operand 9 
In START operand 5 
Logical (see logical expression) 
Extended AGO instruction ( see AGO 
instruction, computed) 
Extended AIF instruction (see AIF 
instruction, extended) 
Extended SETx instruction (see SETx 
instruction, extended) 
External dummy control section (see DXD 
instruction and DSECT instruction) 
External symbol dictionary 
(see also DXD instruction) 
Maximum number of entries 5, 8 
External symbols, maximum number of 5,8 


Format, alternate (see alternate 


statement format) 
Forward scan 25 


GBLx instruction (see declaration of 
SET symbols) 

Generated macro instruction operation 
code 19 

Generated statements, listing of 15 

Global suppression in MHELP options 32 

Global variable symbol (see 
declaration of SET symbols) 


Implicit declaration of SET symbol 25 
Indirect addressing (see created 
SET symbol) | | 
Inner macro definition, (see nested 
macro definitions) | 
Inner macro instruction, passing 
sublists to 20 > ; 
Inner sublist (see multilevel sublist) 
Input sequence checking (see ISEQ 
instruction) 
Input-to-macro instruction (see 
AREAD instruction) 
Instruction format (see statement formae) 
Integer attribute 24 
Internal macro comments statement 14,17 
Interrupted control section 
resuming 
With COM instruction 6 
With CSECT instruction 5-6 
With DSECT instruction 6 
ISEQ instruction ll 
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LCLx instruction (see declaration 
of SET symbols) 
Length attribute 24 
Length of symbols (see symbol, format) 
Local SET symbols (see declaration 
of SET symbols) 
Location counter 
(see also interrupted control section) 
Controlled with the ORG section ll 
LOCTR instruction 6-7 
Multiple location counters 21 
LOCTR instruction 6-7 
(see also location counter) 
Logical expression 29 
"Lookahead mode" (see forward scan) 


Macro AIF dump 32 
Macro branch trace 3l 
Macro call by substitution (see macro. 
instruction, generated operation code) 
Macro call trace 3l 
Macro definition 
(see also macro prototype statement) : 
Comments statement before prototype 14,17 
Maximum number of operands 14 
Nested 13,14 
Placement of 13 
Prototype Operation code 
previously defined 14 
Macro entry dump 32 
Macro exit dump 32 
Macro input instruction (see AREAD 
instruction) 
Macro instruction 
Equal sign in positional operand 20 
Generated operation code 19 
Multilevel sublists in 19-20 
Placement of 19 
Macro name, length of (see ordinary 
symbol, format) 
Macro prototype statement 
Maximum number of operands 14 | 
Nested sublists (see multilevel sublist) 
operation entry 14 
(see also ordinary symbol, format) 
Symbolic parameter format 15 
Macro trace facility 31-33 
Maximum number of ESD entries 5,8 
Maximum number of operands on macro 
prototype 14 
Maximum number of operators in 
logical expression 29 
Maximum number of parentheses in 
arithmetic expression 29 : 
Maximum value of SET symbol subscript 26 
MHELP instruction 31-33 





Model statement 

OPSYN as a model statement 16 
Modifiers 

Symbols to specify the value of 10 
Multilevel sublist 19-20 
Multiple location counters 4, 6-7 
Multiple SET symbol declaration 26 


Nested COPY instructions 4 
Nested created SET symbols 22 
Nested macro definitions 13,14 
Nested sublist (see multilevel sublist) 
Number attribute 
For SET symbol 24 
With multilevel sublists 19-20 


OPSYN instruction 
As model statement 16 
Placement of 12 
To redefine conditional 
assembly instructions 12 
Ordinary symbol, format 2 
ORG instruction 1l 


Parameter format (see symbolic 

parameter format) 
Placement of macro definition 13 
Placement of macro instruction 19 
Placement of OPSYN instruction 12 
Positional operand, equal sign in 20 
Programmer macro, placement of 

(see macro definition, placement of) 
Prototype (see macro prototype statement) 


Q-type address constant 
referencing DXD instruction 7 


Redefining operation codes (see 
OPSYN instruction) 











Scale modifier (see modifiers) 
Scaling attribute 24 
Sequence checking (see ISEQ instruction) 
Sequence symbol format 2,25 
SET sympol 

Created 21-22 

Declaration of 

Alternate format for 26 


Implicit 25 — 
Multiple 25,26 
Dimension 
Maximum 26 
Specifying 26 
Format of 21 
SETC symbol in name field of 
AREAD instruction 16 
SETC variable used in arithmetic 
expression 28-29 
SETx instruction, extended 26-27 
Alternate format 27 
Source macro, placement of (see macro 
definition, placement of) 
START instruction 5 | 
Statement format 
Alternate format (see alternate 
statement format) 
Normal format l 
Sublist 
Multilevel 19-20 
Passed to inner macro 20 
Subscripted SET symbols 
Declaration 26 
open-ended 26 
Substitution in macro instruction 
operation field (see macro instruction, 
generated operation code) 
Symbol 
Format 
Ordinary symbol 2 
Sequence symbol 2,25 
SET symbol 21 
Symbolic parameter 15 
Variable symbol 2 
Symbol attribute reference 
Defined attribute (D') 23, 24-25 
Integer attribute (I') 24 
Length attribute (L') 24 
Number attribute (N') 
For SET symbol 24 
With multilevel sublists 19-20 
Scaling attribute (S') 24 
Type attribute (T') 24 
Symbolic linkages (see external symbols) 
Symbolic parameter format 15 
System variable symbols 
&SYSLIST 17, 19-20 
&SYSLOC 18 
&SYSNDX, MHELP control on 32 
&SYSPARM 17 





Type attribute 24 





Variable symbol format 2 
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Part II: For the MFT or MVT User 








Preface 


This part presents reference information about Assembler H. Specific 
information contained in the following pages supersedes the 
corresponding information for Assembler F that appears in the OS 
Assembler Language, Order Number GC28-6514. Except where contradicted 
by this part, the information in GC28-6514 applies to Assembler H. 


Assembler H operates under the control of OS/MFT or OS/MVT. 
Assembler H supports the features of lower level operating system 
assemblers. Any program successfully assembled with no warning or 
diagnostic message by a lower level OS assembler will assemble correctly 
under Assembler H. 


Knowledge of the IBM System/360 and 370 machine operations, 
particularly storage addressing, data formats, and machine instruction 
formats and functions, is prerequisite to using this publication. So is 
experience with programming concepts and techniques or completion of > 
basic courses of instruction in these areas. IBM System/360 and 370 


machine operations are discussed in IBM System/360 Principles of 


Operation, Order Number GA22-6821, and in System/370 Principles of 
Operation, Order Number GA22-7000. 


You are also assumed to be generally familiar with assembler 
language and with macro and conditional-assembly processing. Such 
information may be found in the following manual, which will be referred 
to in this manual as “the Assembler Language manual." 


OS Assembler Language, Order Number GC28-6514 


This part is a supplement to the Assembler Language manual. To have 
complete documentation of the Assembler H language, you need both the 
Assembler Language manual and this manual. Concepts introduced in the 
Assembler Language manual are not reworked in this manual. 


The structure of this manual parallels that of the Assembler 
Language manual; sections of this book correspond exactly to sections of 
that book. For example, there is no information applicable only to 
Assembler H that corresponds to Section 1 of the Assembler Language 
manual; therefore, this manual begins with Section 2. 


In the text of this manual, braces { } are used to indicate that 
only one of the items enclosed is to be used. Brackets [ ] indicate 
that all the enclosed items are optional. 


Other publications containing pertinent information are the 
following: 


OS Assembler H Programmer's Guide, Order Number SC26-3759 


The Assembler H Programmer's Guide gives detailed information about 
programming with Assembler H, including assembler options and job 
control language procedures applicable to Assembler H. It also explains 
the listing produced by the assembler. 


OS Assembler H Messages, Order Number SC26-3770 
The Assembler H Messages manual provides an explanation of each of 


the diagnostic and abnormal termination messages issued by Assembler H 
and suggests how you should respond in each case. 
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OS_Assembler H System Information, Order Number GC26-3768 


The System Information manual consists of three self-contained 
chapters on performance estimates, storage estimates, and ystoe 
generation of Assembler H. 


OS Assembler _ H Logic, Order Number LY26-3760 


The Logic manual aescribes the design logic and functional 
characteristics of Assembler H. | 


OS Introduction, Order Number GC28- 6534 


The Introduction describes and interrelates all OS control program 
facilities. It shows how these facilities work with the language 
translators and service programs, so you can better learn how to use the 
system. 


OS Job Control Language Reference, Order Number GC28-6704 


The Job Control Language book tells how to code the job control 
language necessary to initiate and control the processing of any 
program, and contains a discussion of cataloged procedures. 


OS Loader and Linkage Editor, Order Number GC28-6538 


The Loader and Linkage Editor manual provides information on the 
operation and use of the loader and linkage editor, which are two 
programs that prepare the output of language translators for execution. 
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Section 2: General Information 


Assembler-Language Coding Conventions 


Continuation Lines 


Nine continuation lines are allowed, ten cards in all. 


Statement Format 


Name Entry: Symbols may be up to 63 alphanumeric characters long. 
External Symbol Dictionary items (contained in START, CSECT, COM, DXD, 
EXTRN, WXTRN, and ENTRY statements, and in Q+type and V-type constants) 
are limited to 8 characters. For all cases, the first character must ke 
a letter. 


Operation Entry: Op codes defined by OPSYN and macro names may be up 
to 63 characters long. 


Terms and Expressions 


symbols 


All symbols except External Symbol Dictionary items may include up to 63 
characters. The first character, or the first character following a 
period or ampersand, must be a letter. 


Ordinary Symbols may contain up to 63 alphanumeric characters. The 
first of these must be a letter. RECORDAREA2, for example, is a valid 
symbol. Special characters and blanks are not allowed. 


Variable Symbols may contain up to 62 alphanumeric characters following 
the ampersand. The first of these must be a letter. 


Sequence Symbols may contain up to 62 alphanumeric characters following 
the period. The first of these must be a letter. 


Note that a valid expression which consists of anything more than a 
Single term is considered by the assembler to be an arithmetic 
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combination of terms. For example, the following expressions are single 
terms: | | 


ALPHA 
L* BETA 
* 


L's 7 
=A (GAMMA) 
12345 
B'1100! 
X*FFFF* 
C'WXYE! 


The following expressions are not single terms, but are arithmetic 
combinations of terms: 


+ALPHA 

(L‘ BETA) 

-12345 

- (ALPHA) 

~ (+ (~BETA) ) 

~2* (BETA-ALPHA) 


Previously Defined Symbols 


Ordinary symbols do not have to be previously defined if they appear in 
operand expressions of ORG and CNOP instructions, in modifier 
expressions of DC, DS, and DXD statements, in the first operand of EQU 
statements, or in Q-type constants. 4 


Allowing forward reference in the above statement types creates two 
new kinds of errors which you should guard against. | | 


e Circular definition of symbols, such as 
4 EQU Y 
b EQU x 
e Circular Location~counter dependency, as in this example: 


A DS (B~-A) C . 
B OLR 1,2 


Statement A cannot be resolved because the value of the duplication 
factor is dependent on the location of B, which is in turn dependent 
upon the length of A. 


Literals may contain symbolic expressions in modifiers, but any 
ordinary symbols used must have been previously defined. See Section 9, 
"Attribute Definition and Lookahead", in this manual. 





Previous Definition of Symbols 


Some coding restrictions are imposed in certain cases where expressions 
are allowed as operands, because the operand field must be processed 
when it is first encountered during Pass 1. The cases are: 


Ce ee ee ee Cpe ee SS ee eT Tee a oe a ep 3 
| Items Affected Fields { 
| | 
}------------------- }----------------~------------------------------- { 
| START statements JAny operand | 
{EQU statements {Expression 2 and Expression 3 (See in this { 
| | manual, “EQU -- Equate Symbol" in 
| | “section 5) 
|Literals {Duplication factor subfield and length modifier | 
| | tela i 

J 


The value of an expression in one of the fields above can be 
determined in Pass 1 only if all symbols in the expression have been 
defined by previous statements (or the same statement). Thus, all 
symbols referenced in these statements must have been previously 
defined. 


In addition, these expressions must have absolute values. Thus, if 
a relocatable term is used, it must be paired with another relocatable 
term, with the opposite sign, from the same section. 


However, paired relocatable terms must be used with caution. 
Assembler H features may have caused temporary segmentation of the 
location counter between the statements which define the two terms of 
the relocatable pair. If this has occurred, the difference of the two 
terms cannot be computed and the expression cannot be evaluated, as it 
must be, in Pass 1. 


Self-Defining Terms 


All types of self-defining terms are extended to 32-bit logical values 
with the number of source digits as follows: 


ne eee tee gD ae ee Ap eee ene eee ne gD oe ee Ow eee eee <eD G o e ee  ee e e ee ee om oe a | 
{Term {Maximum Number [ 
i [Source Tigits [ 
| 


aetna t , 
| Decimal | 10. | 
| Hexadecimal | 8 | 
{Binary | | 32 | 
[ener eres | & | 

1 ee ese eee ae as eee ae J 
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Note: The value of a decimal self-defining term must lie in the range 0 
through 2,147,483,647. A 32-bit hexadecimal, binary, or character 

self- defining term with a 1 in the sign bit is treated as a negative 
number when used in an arithmetic SRPEESSAONS | 


Location Counter Segmentation 


In Pass 1, the location counter is temporarily interrupted (and the 
assignment of temporary values to relocatable symbols is restarted at 
zero) whenever any of the following situations is encountered: | 


® A new LOCTR name is defined. 


e Forward reference or a segmented pair of relocatable terms is used 
in a DC, DS, ORG, or CNOP statement. 


e The location counter cannot be aligned because of a prior 
segmentation. 


® An ORG statement with a blank operand occurs after a prior 
segmentation in the same LOCTR, so that the highest previous 
location-counter setting in the LOCTR is not yet known. 


GENERAL RESTRICTIONS ON SYMBOLS: A symbol may appear only once in the. 
name field of a statement, except for START, CSECT, DSECT, COM, and 
LOCTR names. | | 


Location Counter Reference 


The assembler internally maintains the location counter value as a 
32-bit value. It flags any overflow into the high-order byte as a 
“location counter error“. When this error occurs, the location counter 
will continue to carry the internal value of four bytes, even though 
addressability is limited to three bytes. As an illustration, consider 
the following example: 


pS LS i a a al a eel 
{LOC OBJECT CODE NAME OPERATION | OPERAND 1 
| So | 
fmm a a a a er a { 
1000000 A CSECT | 
{000000  FFFFFE | | ORG oe *¥4+X°FFFFFE' | 
| FFFFFE 58506004 | L oe 5,4 (6) | 
| LEV039 * * #ERROR* * *LOCATION COUNTER ERROR | | 
{000002 O7FF B BR 15 | 
| 000004 01000002 |. Cc DC A (B) | 
io Sigs li ee ln ii i Saas ct le tl tp as i Sai ni sm i sk es a hs ge ae il ie st bn es Sap ds ls i Si cc J 


Note that the location counter value of B prints as three bytes, but 
the location counter value for the address constant at C is four bytes 
Long. 


Location counter values for EQU and USING statements are printed as 
four bytes in the text portion of the listing. The values for COM, 
CSECT, DSECT, DXD, EQU, EXTRN, WXTRN, LOCTR, and START symbols are 
four-byte values in the Cross Reference Listing. 


Literals 
piterars 


Symbolic expressions are allowed in the duplication factor and length 
modifier fields of literals, as well as in the scale and exponent 
modifier fields. Any symbols involved in the duplication factor or 
length modifier must have been previously defined. Thus 


L REG ,= (A) F'6° 
is allowed if A has been defined in the program prior to this statement. 
All literals are cross referenced. Cross reference entries for symbols 


used in literals refer to the literal pool where the literals are 
located, and not to the statements that reference the literals. 


Symbol Length Attribute Reference 


In either of the following instructions 


A EQU  O* 
A EQU "expression'* 


where ‘expression’ consists of a self-defining term or begins with a. 
self-defining term, Assembler H sets the length attribute of A to 1. In 
any EQU statement, Assembler H uses the value of a second operand, if | 
specified, as the length attribute of the symbol in the name field. 

Thus in the statement 


A EQU *,5 
the length attribute of Ais 5. See, in Section 5 of this manual, “EQU 


-- Equate Symbol", and, in Section 9, “Attribute Definition and 
Lookahead". | 


Terms_in Parentheses 


There is no restriction on the number of terms or levels of parentheses 
in an expression. 
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EXPRESSIONS 

Assembler H allows unary operators, as well as binary operators, in 
expressions. 

Unary operators affect the Seszate sign of a single term or 


expression; these are some examples: 


- (L' FIELD) 

+ (BETA-ALPHA) 

== 
A binary operator indicates an operational relationship between two 
terms such as | 

GAMMA+ (BETA~ALPHA) 

ee?) 
A unary operator can precede a term, a left parenthesis, or another 
unary operator; it can begin an expression or follow a left parenthesis, 
unary Operator, or binary operator. 

Thus the rules for coding expressions with Assembler H are: 


e Unary (+, ~,) and binary (+, -, /, *) arithmetic operators are 
allowed in expressions. 


e An expression may Start with a unary. operator. Thus -A, -~X+5, and 
+5 are all valid expressions. 


° An expression cannot contain two terms or two binary operators in 
succession. 


e An arithmetic expression cannot contain a literal. 


Evaluation of Expressions 


Arithmetic operators + or - between terms are evaluated as follows: 


' ia care aac ee ane DR a a ad aa oa ae a ease | 


| Expression {Evaluation | | 


}----------- }----------------- wan an nn a--------- { 
| A+B {B is added to A | 
| | 
{A+-B |The negative of B is added to A [ 
[ | (A+ (-B) | 


Thus it is possible to have any number of plus and minus signs in 
succession between terms. The leftmost (or only) + or - between the 
terms is treated by the assembler as a binary operator. Any arithmetic 
operators to the immediate right of the first are treated as unary 
operators. 


The rules for evaluation of expressions given for Assembler F in 
Section 2 of the Assembler Language manual are valid for Assembler H 
except that: | 





e Expressions are not truncated to the rightmost 24 bits. 


* Unary operations are performed béfore binary operations. The 
sequence of binary orerations is the same: multiplication and 
division are performed before addition and subtraction. 


The final and intermediate results of expression evaluation must lie 
in the range -231 through 23'-1. 


Relocatable Expressions: A simply relocatable expression may have a 
negative value, but the unpaired relocatable term must not be 
algebraically subtracted, or else the expression will be complexly 
relocatable. 
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Section 3: Addressing -- Program Sectioning and Linking 


BASE REGISTER INSTRUCTIONS 


Addresses are broken down into base and displacement form by means of 
the USING statement (Ss) currently in effect. The assembler keeps 32-bit 
positive or negative values for USING statements and prints them in the 
assembly listing. The current USING may be saved by means of the PUSH 
assembler operation and restored later with a corresponding: POP 
operation. (See “PUSH -- Save Current USING or PRINT Status“ and “POP 
~~ Restore USING or PRINT Status", in Section 5 of this manual. 


USING -- USE BASE ADDRESS REGISTER 


A 32-bit signed value corresponding to the first operand of a USING | 
statement is saved and used in subsequent base-displacement computation. 
The value of the first operand is printed as a four«byte value in the 
location counter field. 


The current USING status may be saved with an assembler operation, 
PUSH, and restored later with a corresponding operation, POP. (See in 
this book Section 5, “Listing Control Instructions", "PUSH", “POP".) 


DROP ~- DROP BASE REGISTER 
The operand field of a CROP instruction may be blank. DROP with a blank 


operand field causes all currently active USING registers to be dropped. 


PROGRAM SECTIONING AND LINKING 





The total number of control sections, dummy sections, external symbols, 
entry symbols, external dummy sections, LOCTR instructions, and common 
sections may not exceed 216-1. Note, however, that the lower limits 
imposed by the Linkage Editor and Loader are in effect. See the OS 
Loader and Linkage Fditor manual for details. | 





Control Section Location Assiqnment 


CSECTs and LOCTRs can be intermixed. The assembler provides a location 
counter for each, Each LOCTR after the first in a control section 
begins at the next available byte; that is, the instruction does not 
force location counter alignment. Invalid section names of any type 
default to blank names. See “LOCTR--Define Location Counter®’ later in 
this section. 


START -- Stayt Assembly 


The START instruction is allowed after DxD statements and after DSECT 
and COM sections. The operand of the START instruction may be an 
expression, but any symbols referenced must have been previously 
defined. Location counter reference may not be used, 


CSECT -- Identify Control Section 


Each control section or LOCTR instruction initiates a different location 
counter or continues an interrupted one. All statements following a 
control section or LOCTR instruction are assembled within that location 
counter, until a different location counter is produced by another 
control section or LOCTR. Resuming an interrupted control section 
forces resumption of the most recently active LOCTR in that section. If 
no LOCTR instruction has been specified, the location counter initiated 
by that control section is continued. See “LOCTR--Define Location 
Counter" later in this section. 


DSECT ~~ Identify Dummy Section 


The format of the DSECT instruction is: 


A DSECT instruction may be given a blank name. If more than one 
dummy section is defined, all but one of them must be named because the 
blank name field effectively “names" the dummy section. 


Note: A symbol defined ina dummy section may be used in an A-type or 
Y-type constant which generates RLD items only if ae symbol is paired 
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with another symbol (with the opposite sign) from the same dummy 
section. , : | 


RLD items are generated by A-, Y-, V- or Q-type address constants 
only in a DC operand defined within a CSECT and without a zero 
duplication factor. Both named and unnamed dummy sections may be. 
further segmented by using the LOCTR assembler operation. 


DXD--DEFINE EXTERNAL DUMMY SECTION 


DXD will not generate an ESD item unless the DXD is referenced by a 
Q-type constant that is a control section begun by CSECT or START (or in 
a LOCTR that continues a control section begun by CSECT or START). 


The operand format and alignment is identical to that of the DS 
instruction. See “DS -- Define Storage" in Section 5 of this manual. 


Note: A symbol that names a DXD statement may be used in A- or Y-type 
constants which generate RLD items only if the symbol is paired with the 
same symbol with the opposite sign, as in this example: 





COM -- DEFINE COMMON CONTROL SECTION 


to a nena eee, Senemneneen meena ameemennmenn, onemememmnael 


Assembler H allows named, as well as unnamed, COM instructions. The 
format of the COM statement is as follows: 


As with Assembler F, instructions or data ‘appearing in a common control 
section are never assembled. 


Both named and unnamed common control sections may be further 
segmented using the LOCTR assembler operation. 
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LOCTR ~- DEFINE LOCATION COUNTER 


The LOCTR instruction allows you to define multiple location counters 
within a control section. 


The format of the LOCTR instruction is: 


ecard FO pe sie srr aia ea rian aes aoa aaa panies Meri es eee 1 
| Name {| Operation | Operand | 
| | | | 
~------------- ~----4--------- ~-4------~---~------- ~--------- { 
JA variable symbol |LOCTR | Blank | 
for ordinary symbol | [ | 
eee ees eee | aes antes ee eames 


A control section name automatically names the first location 
counter in that section. A LOCTR instruction with the same name as 
another location counter definition forces a return to that location 
counter, as well as to the control section in which it was defined. 


The assembler will assign consecutive addresses to the statements 
assembled under each new or resumed location counter. A control section 
name is in error if it is identical to a previously defined LOCTR name. 
The length attribute of a LOCTR name is 1. 


A location counter may be interrupted by a CSECT, a DSECT, a COM, or 
another LOCTR. A LOCTR which occurs before the first control section 
will initiate an unnamed control section (private code) before the LOCTR 
is processed. LOCTR does not force location counter alignment. 


This instruction enables you to code logically, defining data for 
instance, where and when the need arises. Figure 1 illustrates location 
counter definition. 


LOC OBJECT CODE ADUR1T ADLUK2 STMT SOURCE STATEMENT 


v00000 1a CSECT LNITLALIZATION 90060000 
vvouo4 2 B LOCTR MALN KOUTINE 90070909 
000008 3 ¢ LOCTR COMPLET LON 00080000 
VOV00E 4 D LOCTR CONSTANTS 00099090 
yu400000 5 USING A,15 ESTABLISH ADDKLSSABILITY VOTOIAO 
voouds 6 B LOCTR BuGIN #1%H MALN ROUTINE 60119000 
YUUUO4 58>Du FO1U 00010 7 i 5,CON20 10120000 
VvOUGE 8 D LOCTR CONSTANE LOCATLON COUNTER 091390900 
UVOOVOE 0000 
vOUUTL 0000U014 9 CON20 pc F'20¢ DirINE THE CUNSTANT NO1BO0OE 
000008 10 B LOCTR BACK ‘LO YHE MALN KOUTINE 90150000 
11 * ~ 09160000 
12 * oa8 N0771000 
13 * BALANCE OF THE MALN ROUTINE 90180000 
14 * mine 00190000 
15 * cae Co700000 
000uV0 16 A LOCTR ANGLLALLZALIUN COUNTER 40210090 
17 SAVE (14,12) INITIALIZATION BEGUN 90229000 
000000 164 DS OH O1-SAVE 
000000 90EC vudE 00v00C 194 STM =. 14, 12, 12 (13) SAVE REGISTERS Q1-SAVE 
000008 20 ¢ LOCTR COMPLELLON COUNTER 00230000 
21 RETURN (14,12) COMPLETLON BEGUN 09231000 
000008 98EC LOVE 0000c 22+ La 14,12,12 (14) KuSTUKE THE REGISTE®S 1-KETUR 
Q000UC O7FE 23+ BR 14 RETUKN A1-RETUR 
24 END 90232000 


Figure 1. Location Counter Definition 


are assigned adjacent addresses in storage. 
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In Figure 1, all statements coded for a particular location counter 
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Symbolic Linkages: There is no practical restriction on the total 
number of control sections, dummy sections, external symbols, ENTRY 
items, and external dummy sections. The effective maximum for each of 
these items depends upon main storage available at linkage edit time, 
and thus may vary from program to program. 
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Section 4: Machine Instructions 


EXTENDED MNEMONIC CODES 


The following extended mnemonics provide RR format instructions which 
correspond to the existing RX format extended mnemonic branch 
instructions. 


ae cre aa aaa es ee ee RL 1g em a a een am em ED ee ee een eee aD ce GD ee aD ee a ee ee ee ee oe DC rn Ee ys et a 


| Extended Code {Meaning * |Machine Instructions | 
| | | | 

--------------- }-----------------------}--------------------4 
| BOR R2 [Branch on Overflow | BCR 1,R2 | 
| | (Ones) | | 
{| BHR R2 {Branch on High | BCR 2,R2 | 
| BPR R2 {Branch on Plus {BCR 2,R2 | 
|BLR R2 [Branch on Low | BCR 4,R2 | 
| BMR R2 [Branch on Minus | BCR 4,R2 | 
| | (@lixed) | 
| BNER R2 {Branch on Not Equal | BCR 7,R2 | 
| BNZR R2 {Branch on Not Zero | BCR 7,R2 | 
| BER R2 |Branch on Equal {BCR &,R2 | 
|BZR R2 [Branch on Zero | BCR 8,R2 [ 
| BNLR R2 |Branch on Not Low } BCR 11,R2 | 
| BNMR R2 {Branch on Not Minus | BCR 11,R2 [ 
| | | (Mixed) | 
| BNHR R2 {Branch on Not High | BCR 13,R2 | 
| BNPR R2 {Branch on Not Plus {BCR 13,R2 | 
| BNOR R2 {Branch on Not Overflow |BCR 14,R2 | 
| [| (Ones) | | 
bse eee boo eee eS oe ek eee eee tie fee Se eee J 


*All instructions are RR format 
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Table of New Instructions © 


The instructions are all privileged. For a description, see the latest 
edition of the IBM System/370 Principles of Operation, Order No. 
GA22-7000. The machine instruction formats are given in the latest 
edition of Assembler Language, Order No. GC28-6514, Appendix C. 










| Literal 
- 2 allowed 
| Machine|Type of (Y=yes, {Storage , 
Instruction Mnemonic | op code/instruction! N=no) alignment 
LOAD REAL 
ADDRESS Y 1 
PURGE TLB* ~ - 


RESET REFERENCE 


BIT RRB 





















SET CLOCK | 

COMPARATOR SCKC 3 
SET CPU TIMER | SPT g 
STORE CLOCK 

COMPARATOR STCKC g 
STORE THEN AND 

SYSTEM MASK  1|STNSM 1 
STORE THEN OR | 

SYSTEM MASK _|STOoSM 1 
STORE CPU 

TIMER ISTPT lg 





*Storage alignment for the storage operand is required. '8' means 
alignment to double word. 


*No operand: if specified is ignored. 
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Section 5: Assembler Instruction Statements 


These two listing control statements are unique to Assembler H: 


PUSH -- Save current USING or PRINT status 
POP -- Restore current USING or PRINT status 


These are discussed later in this section to conform to the 
structure of the Assembler Language manual. 


Symbol Definition Instructions 
EQU -- EQUATE SYMBOL 


The format of the equate instruction is: 


! 
j 
i 
i 
t 
1 
i 
! 
{ 
! 
| 
' 
' 
! 
i 
| 
i 
{ 
1 
! 
! 
| 
| 
| 
{ 
! 
| 
' 
i 
| 
! 
i 
t 
i 
i 
! 
1 
i 
| 
j 
=d 


| Name { Operation 
| | 

fa a a a a cee eee oa 
{A variable | EQU 

{symbol or | 

{ordinary symbol | 


Operand 


a a ee J 
Penne ,Expression2 PEROESs arene | 
| 

| 

a 


er, eXpression3 


-—-—-— — +—-—4 


(= 
{ 
t 
1 
! 
{ 
{ 
! 
| 
! 
1 
{ 
i 
! 
! 
{ 
- 
! 
{ 
i 
t 
! 
' 
i 
| 
! 
! 
! 


Expression 1 must be present and may assume any value allowed for 
assembly expressions: absolute (including negative), relocatable, or 
complexly relocatable. (See the OS Assembler Language manual and this 
book: “Complex Relocatable Expressions" under “Operand Subfield i: 
Constant", in Section 5). Previous definition is not required for 
symbols appearing in Expression 1. 


If the expression is complexly relocatable, the value attribute is 
meaningless. During the evaluation of any expression that includes a 
complexly relocatable symbol, the symbol is replaced by its own defining 
expression. Thus if Ail and A2 belong to one control section and Bi and 
B2 belong to another, and if these equate statements have been used: 


On ee ee Voge ee ee ee pleas oasis Ca gaa 1 
| Name | Operation: | Operand 
| | | | 
pasaaso aaa ae senna Payee nates SESS SAS ca a wR { 
|X | EQU [A1+B1 | 
| |. | | 
| | | | 
| | - | 
LY | FOU |X-A2-B2 | 
eee ea een ne Mee eet ee Beyer cates tates: ba Ne eA er ey OR ONE Taree Teal Ae i 


then X is complexly relocatable but Y is absolute. 
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Expression 2 and Expression 3 are both optional and any symbols 
appearing in their operands must have been previously defined. Both 
expressions, if present, must be absolute. 


The value of Expression 2 must be in the range 1 through 65536. The 
value of Expression 2 overrides the normal length attribute of the 
symbol in the name field. Two commas following Expression 1 indicate 
the absence of Expression 2 and the presence of Expression 3. If 
Expression 2 is omitted, the length attribute of the symbol in the name 
field is based on the leftmost (or only) term of Expression 1: 


° If it is an asterisk (which references the current value of the 
current location counter) or a self-defining term, the length 
attribute is 1; 


e If it is the name of a DC or CS instruction, the length attribute 
equals the implicit or explicit length of the first constant. 


° If it is the name of a machine instruction or channel command word, 
the length attribute is the length of the instruction itself. 


The value of Expression 3 must be in the range 0 through 255. The 
value of Expression 3 overrides the normal type attribute of the symbol 
in the name field. The corresponding EBCDIC character is taken as the 
type attribute. 


For example, 


Re Oe ae Ne Qe rey we ee een ee ee 1 
| Name | Operation | Operand | 
| | | | 
}------- ------------ t----------- }-------------- ~~------------ { 
[A | EQU |SYM,13,194 | 
Ee aero ae fe nee en Pon oto sees a eee einer meaner any Se ea J 


The value of A is that of SYM, the length attribute is 13, and the type 
attribute is the letter B. The same type attribute could be achieved by 
writing C'B', xX'C2", or B'11000010' as the third operand. If Expression 
3 is not present, the type attribute defaults to "U". 


OPSYN -~x EQUATE OPERATION CODE 


The OPSYN instruction is used, as with Assembler F, to redefine or 
delete existing operation codes or to define new operation codes 
equivalent to existing ones. The modified format is: 


Operand | 
| 
Ste a aN a ae a ae a an eater eee 4 


| 

| 

+ 7 : 

| OPSYN {A machine instruction 
| {mnemonic code, an extended 
| [mnemonic code, a macro 
| 

| 

| 

| 

| 

L 


jor variable symbol 


foperation, an assembler 
foperation, an operation code 
{defined by a previous OPSYN 
finstruction, or a blank. 


fe ne eee eee ree ee eee 
fue emme annem anemen cue GED GED an eo 
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The symbol in the name field may be a previously defined operation © 
code. The latest definition takes precedence. The OPSYN mechanism does 


not search the macro library for possible system macro definitions. 
Thus: 


ERIE ORIYA LOIN CERT CRED GBR CET CRG GENND ERIE CUED ABAD SUNT CUED CEN “ED ERS ate EP TEN GND eT? COND <EFIR «Been ee A ee: ee 


will yield the desired results if DCB has been expanded or edited (as in 
COPY DCB) prior to this OPSYN. Otherwise, DCB will be flagged as an 
undefined opcode, and PDQ will be flagged when used later on. 


If you want to prevent the assembler from recognizing the operation 
code in the name field, use the following format: 


or > aa erp ee a ae Ee Gem em oe 


T T 

| Name | Operation | Operand | 
| | ! | 
}~-~---------------- +------------ }---------------------------- { 
[A mnemonic | OPSYN | Blank | 
[operation code | | | 
| | | | 
bisote oS oes faa en ne eae Mia Seances a note ayaa ee eos Set as Dd J 


OPSYN symbols conflict in no wey with the use of the same symbols as 
names on other statements. 


OPSYN statements are ignored by lookahead. You should therefore 
especially beware of an OPSYN involving COPY within a lookahead request, 
or an OPSYN involving END. If such OPSYNs are used, they should be 


placed early in the program before any statement that May initiate 
lcokahead mode. 


Data Detinition Instructions 





Literal Definitions: The following rules differentiate the coding of 
bins terals from the coding of constants: 





@ The literal is preceded by an equal Sign. 


@ Multiple operands may not be specified. 


@ Every symbol in an expression used to specify the duplication factor 
or length modifier must have been defined by appearing in the label 
field of a previous (or the same) instruction. 


e The duplication factor may not be zero. 
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DC -- DEFINE CONSTANT 


Operand Subfield 1: Duplication Factor 


With the exception of literals, as noted above, symbols in the 
expression need not have been previously defined. 


Operand Subfield 3: Modifiers 


With the exception of literals, as noted above, symbols used as 
modifiers need not be previously defined. The length attribute of the 
current statement name is not available for use in the length modifier 
expression of the first operand for that statement. 


Scale Modifier: Symbols used in an expression need not have been 
previously defined. 


Exponent Modifier: Symbols used in an expression need not have been 
previously defined. 


Operand Subfield 4: Constant 


X-Type and B-Type Constants: Multiple constants are allowed in X- or 
B-type operands. 


V-Type Constants: V-type constants with zero duplication factors will 
not generate ESD items. 


S-Type Address Constant: S-type address constants can be used in 
literals. Address decomposition into base and displacement form is 


based on the USING staterents in effect at the associated literal pool. 


-~-Type Address Constants: QO-type address constants can also be used in 
literals. Previous definition is not required for DXD or DSECT names 
referenced in Q~type constants. A Q-type constant with a zero 
duplication factor will not generate an ESD item. 
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DS _-- DEFINE STORAGE 


The format of the DS operand is identical to the DC operand. See above, 
"DC ~- DEFINE CONSTANT". 


Listing Control Instructions 


TITLE -- IDENTIFY ASSEMBLY OUTPUT 


Only one TITLE instruction, but not necessarily the first, can have a 
name other than a sequence symbol. The name field in a TITLE 
instruction may contain from one to eight non-blank characters. The 
contents of the name field of the first named TITLE statement are 
punched into the output cards beginning in column 73. Any remaining 
columns in the sequence field are devoted to deck sequencing. Output 
cards produced in the program by PUNCH and REPRO assembler instructions 
are not affected by a TITLE instruction. 


Note: If the name Field Starts with a period, it is considered to be a 
sequence symbol. 


PRINT -- PRINT OPTIONAL DATA 





The PRINT instruction is allowed within macro definitions. The PRINT 
statement is always printed, except when PARM=NOLIST is coded in the 
EXEC statement that includes Assembler H, regardless of print options 
already in effect. 7 | 


NE a Aa ir arial 


PUSH -~ SAVE CURRENT USING OR PRINT 2 


PUSH may be used to save the current PRINT or USING status in push down 
Storage. Conditions may be restored later on a last-in-first-out basis 
by the use of a corresponding POP operation. PUSH does not change the 
PRINT or USING peers in effect. The format for the PUSH instruction 
is as follows 


18 


eer rag ee Me ee ay er ee ee pe % 
| Name | Operation | Operand | 
| | | 
}-~---~-------~ ~----+----------- }---7----------~---~--------- { 
|Sequence symbol or |PUSH l USING (, PRINT] | l 
| blank | PRINT Pus ane). | 
| | | | | 
Daa nee a ae SE ae eae ete eee Deets aera hee eet J 


The operands may appear in either order. At least one of them must be 
specified. | 


POP ~~ RESTORE USING OR PRINT STATUS 


The POP assembler instruction is used to restore the PRINT or USING 
status saved by the most recent PUSH operation. The format for the POP 
instruction is: 


Sr eg es Me ee ie eee ere gO ve 1 
| Name { Operation | Operand | 
| | | | 
|}--~--~-------------- }----------- fran an nn nnn neem enn nn { 
|Sequence symbol or |POP | USING [,PRINT] 
| blank | | | PRINT [,USING] 
| | | | 
Liticatenet See fo ee ee De Sas Sa ee ee J 


The operands may appear in either order, and need not be in the order in 
which they appear in the PUSH statement. 


ISEQ ~~ INPUT SEQUENCE CHECKING 


Sequence columns to be checked may be anywhere on the card, and thus may 
be between the begin and end columns as defined by the ICTL instruction. 
The EBCDIC collating sequence is used. An out-~of-sequence card will 
produce an error diagnostic. 


A blank field being checked for Sequencing will produce a warning 


diagnostic, but the checking will continue, relative to the last card 
with a non-blank sequence field. 
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Program Control Instructions 


ORG == SET LOCATION COUNTER 


The general form of this instruction is: 


ia aaa ca a mac ee ge ey aS et Pa 1 
| Name j Opferation | Operand | 
| | | | 
aS townn nanan n= ae Sas UES EP RSE { 
{Any symbol or blank]|ORG {A relocatable expression or | 
| | | blank | 
| | | | 
Ue ee DS ah haath Sa eee OU ce aha a ea a ea ee J 


In general, symbols used in the operand need not have been 
previously defined. However, the simply relocatable component of the 
operand (that is, the unpaired relocatable term) must have been 
previously defined, or equated to a previously defined value. The 
resolved value of the orerand must fall in the same LOCTR as the ORG 
instruction. (See this manual, “LOCTR -- DEFINE LOCATION COUNTER" for a 
discussion of that instruction.) Remember that CSECT, DSECT, and COM, as 
well as LOCTR instructions, define a location counter. 


The ORG statement cannot be used to reference a location outside the 
location counter in effect when the ORG is assembled. A negative value 
is thus not allowed. 


A symbol in the name field of an ORG statement is assigned the value 
of the location counter prior to the application of the ORG. An 
asterisk (*) in the operand field has the same value as the symbol in 
the name field. The location counter value, both before and after the 
processing of the ORG, will appear in the assembly listing. 


An ORG statement with a blank operand causes the current location 
counter tc be reset to the highest previous setting within the current 
LOCTR. 


Special Addressing Consideration 


Ail literals not located by LTORG statements within the program are 
placed at the end of the most recently active LOCTR in the first control 
section. This includes the case where literals are used after the last 
LTORG statement in the program as well as the case where no LTORG 
statements are used at all. 
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CNOP -~ CONDITIONAL NO OPERATION 


The format of the CNOP statement is as follows: 


CP ne ee ee Te a ee ee ee ere gee 1 
| Name | Operation | Operand | 
| | | | | 
~------------------ }-----------}----------------------------4 
{Any symbol or blank|CNOP {Two absolute expressions, [ 
| ] |separated by commas ! 
| | | | 
Ut Se es ee eae ene eee ee a a J 


CNOP causes initial halfword alignment, if required. Then the symbol in 
the name field is assigned the value of the current location counter, 
and the alignment specified in the operand is completed. 


| An -asterisk (*) in the operand field is assigned the same value as 
the symbol in the name field. Symbols appearing in the operand 
expression need not have been previously defined. 


COPY ~~ COPY PREDEFINED SOURCE CODING 


Any statement (except ICTL) is allowed within copied code, so long as it 
conforms to the following rules: 


e COPY statements may be nested to any level, but may not be 
recursive. Thus in the statement “COPY A,“ if A contains the 
statement “COPY B“ and B contains the statement “COPY C,“ the copy 
requests are valid unless B contains the statement “COPY A," or C 
contains either “COPY A“ or “COPY B". 


e If a copied partitioned data set member includes a MACRO statement, 
it must also include the corresponding MEND statement. 


e If an END statement or an OPSYN equivalent is encountered, either | 
inside or outside copied code, the assembly is terminated. In EATCH 
mode, the next assembly begins with the next card in the SYSIN 
stream. 


COPY statements are executed during lookahead and the copied text is 
scanned. See Section 9, “Attribute Definition and Lookahead"“. 


END ~- END ASSEMBLY 


The END instruction terminates the assembly whenever it is encountered 
in the source stream, in copied code, or during the expansion of a macro 
instruction. The END statement is treated as a model statement in a 
programmer or library macro while the macro is being edited. 
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MNOTE ~-- REQUEST ERROR MESSAGE 


» 


MNOTE instructions may be used in open code. They have all the 
properties of macro instruction MNOTEs. 7 | 


The severity code is optional. If it is omitted, the MNOTE becomes 
a comment starting in the begin column, and is not treated as a 
diagnostic. 
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Section 6: Introduction to the Macro Language 


The Macro Instruction 


All macro instructions in Assembler H are mixed mode, which permits you 
to use the features of bcth positional and keyword operands within the 

same macro instruction. Positional and keyword operands may appear in 

any sequence. 


The Macro Definition 


The prototype statement specifies only the mnemonic operation code and 
parameters; defining the type of instruction is not necessary, because 
all macro instructions for Assembler H are considered mixed mode. 


SYSTEM AND PROGRAMMER MACRO DEFINITIONS 


Programmer macro instructions may appear at any point in the assembly 
source text. However, the assembler must encounter a macro definition 
for a given macro prior to the first call to that macro. Otherwise, the 
INMacro instruction will be fetched from SYSLIB or treated as an undefined 
operation code. The assembler flags a syntax error in a programmer 
macro immediately following the erroneous statement in the listing. 


Source syntax errors in system macro definitions are flagged 
immediately after the first call to the macro. A system macro can be 
processed (and therefore listed) as a programmer macro if a COPY is 
issued to copy the entire macro definition into the source text before a 
call is made to the macro. For instance: 


ia a aaa ca a a a aaa al te eae ee eee 1 
| Name {| Operation | Operand | 
| | | 

}------------------- +----------- }---------------------------- { 
| | COPY | SYSMAC | 
{ {| CSECT | 
| [| USING [*,12 | 
| | BALR {12,0 1 
Ae ee eal p Bennet en ae eee ey Ate aes ata ele ee ee J 


In this case, SYSMAC is a cataloged system macro. It is copied into the 
source text, and errors, if any, are flagged as in programmer macros, 
immediately following the erroneous statements in the listing. 
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Variable Symbols 

A variable symbol may contain up to 62 alphanumeric characters after the 
ampersand. The first character following the ampersand must be a 
letter. | : | | 


Global SET Symbols 


Global and explicit local definitions of SET symbols can occur anywhere 
in open code or in macros, as long as the definitions precede the first 
use of the SET symbol. 


Section 7: How to Prepare Macro Definitions 


Programmer macro definitions can appear at any point within the assembly 
source text. However, the assembler must encounter and edit the 
definition of a given macro prior to the first call to that macro. It 
is also possible to redefine a machine or assembler instruction 
operation code by including a macro definition in the program. 


A macro definition may appear within another macro definition. This 
feature is discussed later in this section under "Nested Macro 
Definitions". : 


Macro Instruction Prototype 


The symbol appearing in the operation field may be any valid ordinary 
symbol up to 63 characters long. This includes machine operations, 
assembler operations, extended mnemonics, etc. A maximum of 240 
parameters is permitted in a prototype statement. . 


All macro definitions are considered to be in mixed mode. 
Positional and keyword parameters may be mixed freely in both the 
prototype and the call. The positional parameters are processed from 
left to right, skipping over the keyword parameters. 


The default values specified for keyword parameters can contain 
sublists nested within sublists. They can also contain embedded equal 
signs. | 


Model Statements 


The different fields in a macro-generated statement or a statement 
generated in open code appear in the listing in the same column as they 
are coded in the model statement, with the following exceptions: 


e If the substituted value in the name or operation field is too large 
for the space available, the next field will be moved to the right 
with one blank separating the fields. 


e If the substituted value in the operand field causes the remarks 
field to be displaced, the remarks field is written on the next 
line, starting in the column where it is coded in the model 
statement. 


e If the value substituted in the operation field of a macro-generated 
statement contains leading blanks, the blanks are ignored. 


@ If the value substituted in the operation field of a model statement 


in open code contains leading blanks, the blanks will be used to 
move the field to the right. | 
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Nested Macro Definitions 


Macro definitions may appear within other macro definitions to any 
level. These nested definitions are edited only when the macro 
definition header is encountered during expansion of the immediately 
containing macro. 


Consider the following example: 


ooo ee Wee Go te ret oe a aa aa a | 
| Name | Operation | Operand [ Comments | 
| 2 | | 
}----~--}----------- }------------------- +~----------------------------- { 
| | MACRO | | Header 

| | OUTER 16A,&B, &C=ED { 

| | AIF | (K'&C EQ 0).A 

] | MACRO { | Header 

| | INNER |SE, &F, &G, §H= | 

| ‘ | |Nested definition of INNER 

| : | | 

i | MEND i {Trailer 

[A | MEND 

| | | | Trailer 

[ 

bossa San Enya ener eit Berea ies See ou a Oe ac psec ee rg a cag ee rae aes 


In order for INNER to be edited and recognized as a macro instruction, 
OUTER must be encountered as a macro instruction and &C must have a 
non-zero length. 


The operand parameters of a nested macro definition prototype are 
distinct from those of the containing macro. 
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Inner Macro Instructions 


An operand of an outer macro instruction sublist may be passed as a 
sublist to an inner macro instruction. 
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a aera ac re aodariaad er Tp Sm a a a ge aa ee 1 
[ Name [ Operation | Operand j 
| | | | 
~--------- n--------}-----------}----------------------------f 
| SABC | SETA | SABC+1 
| 6X (&X (1) +1) | SETA {1 
Scdeiag aciocies aides seat gt eens cia Di cic ediint Cat ob ok er ecabe ian everest eran aerate oi oe eas Saeed 
Attributes 


Attributes of symbols produced by macro expansion or open code 
substitution are available immediately after the defining statement is 
generated. 


Within the proper context of a SETA, SETB, or SETC expression type 
(T'), length (L‘'), scaling (S‘), integer (I'), and defined (D', see 
below) attribute reference may be made to a macro instruction parameter, 
to a SETC symbol inside a macro definition, to a SETC symbol or an 
ordinary symbol in open code, or to ordinary symbols produced by macro 
expansion or open code substitution. 


Count (K‘) attribute reference may be applied to all SET variables. 
In the case of SETA and SETB variables, the value of the variable is 
first converted to a character string and leading zeros are discarded. 
If the character string is composed of one or more zeros, the rightmost . 
character is a significant digit and the value of count attribute is 1. 
In the following example, 


(rate Ne fa ee Tn ee ee pay 9 ere ee OTE eet mCn 1 
| Name | Operation | Operand | 
------------------- }~---~------}----------------------------4 
| 6A | SETA {0100 { 
| 6B | SETB 10000 { 
bee Se ee ee Leceoecaceass tala eta as wef a  aa osaaea 4 


K'&A equals 3 (the leading zero is lost) and K‘&B equals 1. 


The number (N‘') attribute may be applied to subscripted SET 
variables. The number (N‘) attribute is the highest subscript value 
that has been involved in a receiving Operation. For example, if the 
only references to variable symbol &A have been the following, 


Ce ee ee Eee re fee re an pe Re ne Te een GFF 1 
{ Name | Operation | Operand j 
| | ! 
75a Re forma wae fener nnn nan 
| 6A (5) | SETA |20,,,70 l 
(AIF | (6A (20) GT 50) .M 
ene ao neae ee ere ea CRE ePenEa RE ery SERN cr tee a mere i a Si i a a eas aca od Sal ear J 


then N°'SA equals &. (Refer to Section 10, “Extended SET Statements".) 
An attribute reference to a variable symbol whose value is an 


arithmetic expression, in which the leftmost term is a symbol, returns 
the attribute of that symbol. | 2 
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Definition Mode 


Definition occurs whenever a previously undefined symbol is encountered 
in the name field of a statement, or in the operand field of an EXTRN or 
WXTRN statement during open code processing. Symbols within a macro 
definition are defined when the macro is generated. 


Lookahead Mode 


Lookahead is a sequential, statement~by-statement, forward scan over the 
source text. It is initiated when reference is made to an attribute 
(other than D‘) of a symbol not yet encountered, either by macro or 
open-code attribute reference, or by a forward AGO or AIF branch in open 
code. 


If reference is made in a macro, forward scan begins with the first 
source statement following the outermost macro instruction. Programmer 
Macros are bypassed. The text is not assembled. Lookahead attributes 
are tentatively established for all intervening undefined symbols. 
Tentative attributes are replaced and fixed when the symbol is 
subsequently encountered in definition mode. No macro expansion or 
open-code substitution is performed; no conditional or unconditional 
(AIF or AGO) branches are taken. COPY instructions are executed during 
lookahead, and the copied statements are scanned. 


Lookahead ends when the desired symbol or sequence symbol is found, 
or when the END card or end of file is reached. All statements passed 
over by lookahead are saved on an internal file and processed when the 
lookahead ends. 


For purposes of attribute definition, a symbol is considered 
undefined if it depends in any way upon a symbol not yet defined. For. 
example, if the symbol is defined by a forward EQU that is not yet 
resolved, or if a DC, DS, or DXD modifier expression contains symbols 
not yet defined, that symbol is assigned a type attribute of U. 


NOTE: Since no variable symbol substitution is performed by lookahead, 
you should be careful when using a macro or open code substitution to 
generate END statements that separate source modules assembled in one 
job step (option BATCH). If a symbol is undefined within a module, 
lookahead will read in records past the point where the END statement is 
to be generated. All statements between the generated statement and the 
point where lookahead stops (either because it finds a matching symbol, 
or because it finds an END statement) are ignored by the assembler. The 
next module will start at the point where lookahead stops. 


Lookahead Restrictions 


Assembler statements are analyzed only to the extent necessary to 
establish attributes of symbols in their name fields. 


Variable symbols are not replaced. Modifier expressions are 


evaluated only if all symbols involved were defined prior to lookahead. 
Possible multiple or inconsistent definition of the same symbol is not 
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The following code will convert a hex value in 6H into a decimal 
value in &VAL: 


Reet ee rey MR ye ea te Nee epee an eee ere ee ge 1 
| Name | Operation | Operand | 
| | | | 

manne nnn nanan onan nnn nn fence n nnn nnn enn nana 
| 6X | SETC }*X**éH''® [ 
| &VAL | SETA }&X [ 
arses a as ies el a ee Le Sele 6S aie eae eee eer a F) 


An arithmetic expression may not contain two terms in succession; 
however, any term may be preceded by any number of unary Operators. 
+&6A*-&B is a valid operand for a SETA instruction. The expression 
&FIELDt- is invalid because it has no final term. 


Evaluation of Arithmetic Expressions 


The number of levels of parentheses in a SETA arithmetic expression must 
not exceed 255. 


SETC -- Set Character 


Any of the expressions permitted in the operand field of a SETC 
statement (a type attribute, a character expression, a substring, ora 
SETA symbol) may optionally be preceded by a SETA expression enclosed in 
parentheses to be used as a duplication factor. If &J has a value of 3, 
the following two statements are equivalent. ? 


Ce ee ee Tee eg ae eg ey fs 1 
. Name | Operation | Operand | 
~------------------ 4}-~---------}-~-~----~--------------------| 
| éC { SETC | (2) *X¥°. (&J+1) "PDQ" ] 
a ees eee SPEDE Pore ! 


Note: If a SETC duplication factor and a substring are used in the same 
SETC statement, the substring is evaluated first, and the duplication 


factor is evaluated second. For example, the following statement will 
yield “BCBC", not “BCA". 


Re REP we omen eee ate aawe en ann eer eee 
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{Operation Operand | 





Consider the following example: 


('&L' (&C,1) 7 .DOLR,('&L'(&C,1) EQ '#').POUND, 
('&L' (&C,1) AT, ('&L'(&C,1) EQ '='). EQUAL, 


('&@L' (&C,1) .LEFTPAR, ('&L'(&C,1) EQ '+').PLUS 
("gL' (&C,1) .MINUS 


This routine looks for the occurrence of a $, #, 2, =, (, +, and -, in 
that order; and causes control to branch to .DOLR, .POUND, .AT, .EQUAL, 
-LEFTPAR, .PLUS, and .MINUS, respectively, if the string being examined 
contains any of these characters. | 


Note: The example shown above indicates that the alternate format is 
allowed for this statement. Refer to “Alternate Format in Conditional 
Assembly“ in Section 10. 


AGO -- Unconditional Branch 


COMPUTED AGO STATEMENTS 


The computed AGO statement has the following format: 


Gt ee eran ee De eg ge ee re Oe re ST 1 
| Name | Operation | Operand | 
| | | | 
}------------------- {------~---- {—----------=---------------- { 
{A sequence | AGO [|farithmetic \ .S1,.S2,...,.Sn| 
[symbol or | |\ expression [ 
| blank | | | 
bie ee ee yee a eee ena DS es oe eee J 


If the arithmetic expression evaluates to k, where k lies between 1 and 
n (inclusive), then the branch is taken to the “k-th" sequence symbol in 
the list. If k is outside that range, no branch is taken. 


In the following exarrple: 


eee EM Nh eae ante te cay atte ate ERD eae GR alr neh Com Ee a a ue Ome ain can Gl Ge agin eae eee 


control passes to the statement at .THIRD if 6I=3. Control passes 
through to the statement following the AGO if &1 is less than 171 or 
greater than 4. | 
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Section 10: Extended Features of the Macro Language 


MNOTE - Request for Error Message 


The MNOTE instruction may be used either in open code or macro 
definitions. The severity code is optional. If it is omitted, the 
MNOTE becomes a comment starting in the begin column and is not treated 
as a diagnostic. 


Global and Local Variable Symbols 


Defining Local and Global SET Symbols 


Global and local declarations may occur anywhere. Such declarations 
must precede any reference to the symbol to be effective in the 
generation process. 


Alternate Format in Conditional Assembly 


Alternate format allows a group of operands to be spread over several 
lines of code. Each line, except the last, is followed by a comma, one 
or more blanks, and a non-blank character in column 72. Comments are 
inserted optionally between the blank and column 72. In addition to 
macro prototype and macro call statements, alternate format can be used 
for extended AGO, AIF, and SETx statements, and GBLx and LCLx 
declarations. 


Subscripted SET Symbols 


SET symbol definition is discussed in “Defining SET Symbols* in Section 
9 of this book. A subscripted SET symbol is declared explicitly by 
following the symbol with a positive, decimal self<defined number 
enclosed in parentheses. A subscripted SET symbol is implicitly 
subscripted if it occurs first in the name field of a SET statement in 
subscripted notation. The subscript limit is open-ended and may be 
raised at any time simply by writing a higher number between the 
parentheses. 
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Extended SET Statements 


A single SET statement can assign values to muitiple elements in an 
array. Consider the following example. 


5,10,15,20,25,30 
se i a si en eid i sm su i ns cr easing on ey so 4 


The SET declaration defaults to LCLA if there has been no previcus 


global or local declaration of SARRAY. The subscript of the variable 


symool is incremented by 1 for each operand value. Following the above 


instruction, &ARRAY(1) has a value of 5, SARRAY(2) has a value of 10, 


and so forth. 


If one of the operands is omitted, the corresponding element of the 


array is unchanged. In the following example, 


Geer ee ne is fe ce eee Ge ye ee ee ee 1 
| Name | Operation | Operand | 
| | | | 
}------------------- {----------- }---------------------------- { 
| LIST (6) eee Pee leer 20e2ae se | 


the elements referenced by &LIST (6) and &6LIST(9) are left unchanged. 
Note that N*&LIST=12 if this is the only statement involving é&LIST. 


Alternate format may be used for the operands of an extended SET 


statement, as with the operands of a macro call or macro definition. . 


Thus, the above coding could be written as follows: 


pace saccades eo ee a Sa i a a a a 
| Name | Operation | Ope rand | Column 72 

| | | | 

}----------- +----------- {--------------- }---------------------------- 
| &LIST (6) | SETA (¢S% |X 

| | [ 10, [x 

| | |,20, 25, 30 l 

ie eS oe ee Beh oA te Si ai at ae ad ls es See ee ea ee ee an OD a yee IEE eae 


Created SET Symbols 


J 


i 
1. 
ake 


! 
t 
i. 


A created SET symbol has the form & (e) where "e" represents a sequence 


of one or more of the following: 
e Variable symbols, optionally subscripted. 
° Strings of alphanumeric characters. 


e Created SET symbols. 
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ceo a a a a 1 
| Name { Operation | Operand { 
| | | 
panna anna tome nn nnn fran me mene nnn nana 
{A sequence symbol |MHELP [Absolute expression, binary | 
jor blank { Jor decimal options as | 
| | {discussed below. [ 
| | | | 
wba oue eee Boni ee ee eet ee ei oes a eae J 
Macro Call Trace ~-- Operand=1 


This option provides a one-line trace listing for each macro call, 
giving the name of the called macro, its nested depth, and its &SYSNDX 
value. The trace is provided only upon entry into the macro. No trace 
is provided if error conditions prevent entry into the macro. 


Macro Branch Trace ~- Operand=2 


This option provides a one-line trace listing for each AGO and AIF 
conditional-assembly branch within a macro. It gives the 
model-statement numbers of the “branched from" and the “branched to" 
statements, and the name of the macro in which the branch occurs. This 
trace option is suppressed for library macros. 


esate oe Reena 


Macro AIF Dump -- Operand=4 


This option dumps undimensioned SET symbol values from the macro 
dictionary immediately before each AIF statement that is encountered. 


Macro Exit Dump -- Operand=8 


This option dumps undimensioned SET symbols from the macro dictionary 
whenever a MEND or MEXIT statement is encountered. 


Macro Entry Dump -- Operand=16 


This action dumps parameter values from the macro dictionary immediately 
after a macro cali is precessed. 
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System Variable Symbols 


There are four new system variable symbols available--&SYSUCATE, 
&SSYSTIME, &SYSPARM, and &SYSLOC--in addition to &SYSNDX, &SYSLIST, and 
ESYSECT. 


&SYSPARM, &SYSTIME, and &SYSDATE may be used as desired in macro 
definitions and open code. &SYSNDX, SYSECT, &SYSLIST, and &SYSLOC may 
be used only inside macro definitions. 


&SYSLIST ~- Macro Instruction Operand 


&ESYSLIST refers only to positional macro instruction operands. 
Interspersed keyword operands are skipped over during &SYSLIST 
reference. 


&SYSDATE -- Date of Assenbly 


ESYSDATE provides the date of the assembly and corresponds to the date 
printed in the page heading. The value of &SYSDATE is the 8-character 
string mm/dd/yy (month/day/year). The value remains constant throughout 
the assembly, and may be used both inside and outside macro definiticns. 


&ESYSTIME -- Time of Assembly 


&ESYSTIME provides the time printed in the page heading. The value of 
ESYSTIME is the five-character string hh.mm (hours.minutes). As with 
&SSYSDATE above, the value remains constant and may be used both inside 
and outside macro definitions. 


For systems without the internal timer feature, &SYSTIMF is a 
five-character string of blanks. 


&SYSPARM -- User Assembly Parameter 


The system variable &SYSPARM operates in conjunction with the SYSPARM 
parameter in the PARM field of the EXEC card in the JCL sequence. 
Together they allow you to control conditional assembly flow and code 
generation through the use of an externally specified parameter. The 
value of &SYSPARM is the character string specified in the SYSPARM 
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&SYSDATE 45 

&SYSLIST 45 

&SYSLOC 46 

&SYSNDX 
MHELP control on 44 

&SYSPARM 45-46 

&SYSTIME 45 

*value 
In CNOP instructions 21 
In location counter reference 15 
In ORG instructions 20 


Absolute expressions 3,14 
ACTR instruction 38 
Address constants 17 
AGO instruction, computed 37 
AIF instruction, extended 36-37 
Alignment, location counter 9 
Alternate format 37,39,41 
ANOP instruction 38 
AREAD instruction 30 
Repeated AREAD statements 30 
Within copied code 30 
Asterick value 
In CNOP instruction 21 | 
In location counter reference 15 
In ORG instruction 20 
Attributes 31-33 
See also symbol attributes 
Defined 32 
Definition of 31,33 
Definition mode 33 
Lookahead mode 33 
Lookahead restrictions 33-34 
What can be referenced 31 





B-type constants 17 | 
Base register instructions 8 
Binary operators 6 | 

BER branch instruction 13 
BHR branch instruction 13 
BLR branch instruction 13 
BMR branch instruction 13 
BNER branch instruction 13 
BNHR branch instruction 13 
BNLR branch instruction 13 
BNMR branch instruction 13 
BNOR branch instruction 13 
BNPR branch instruction 13 
BNZR branch instruction 13 
BOR branch instruction 13 


Index 


BPR branch instruction 13 
Branch instructions 13 
BZR branch instruction 13 


Cataloged macro 
See system macro 
CNOP instruction 21 
COM instruction 10 
Complexly relocatable symbols 14 
Computed AGO instruction 37 
Constants 17 
Continuation cards 
Alternate format 37,39,41 
Normal format lL 
Control section, interrupted 9 
COPY instruction 21 
Copying macros 21 
END statement encountered during 
execution of 21 
Within copied code 2l 
Nested 21 
Recursive 21 
Created SET symbols 41-42 
CSECT instruction 9 





DC instruction 17 
Definition mode 33 
Definition of SET symbols 
Explicit 30 
Implicit 30 
DROP instruction 8 
DS instruction 18 
DSECT instruction 9-10 
DXD instruction 10 | 





END instruction 21 
Encountered in copied code 2l 
EQU instruction 14-15 
Equals sign, embedded in macro 
parameters 28 
Explicit definition of SET 
symbols 30 | 
Exponent modifier 18 
Expressions 
Evaluation of 6-7 
Rules for coding 6 
Extended AGO instruction 
See computed AGO instruction 
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Q-type address constants 17 


Relocatable expressions 7 
Relocation Dictionary items in DSECTS 9-10 
RLD items 

See Relocation Dictionary 

items 


S-type address constants 17 
Scale modifitier 17 
Segmentation of location counter 4 
Self defining terms 3-4 
Sequence symbols. 
Use of in name field 34 
SET instructions 
Extended 41 
SET symbols 
Created 41-42 
Definition 
Explicit 30 
Implicit 30 
Multiple 34 
Placement 24,34 
Subscripted 39-40 
SETA instruction 34-35 
As duplication factor in 
SETC instruction 35 
Levels of parentheses in 35 
SETC instruction 
Character length, maximum 36 
Evaluation of duplication 
factor and substring 35 
Operand as arithmetic term 34 
Substring, maximum character 
value 35 
START instruction 9 
Statement format l 
Sublists 
Multi-level 28 
Outer macro sublist 
As inner macro sublist 29 
Subscripted SET symbols 39-40 
Definition of 39 
Open-ended limit 39 
Substitution 
Operation codes that can't be © 
created by 26. | 
Substring, maximum character 
value of 35 
Symbols 
Definition 14-15 
Format 
Ordinary symbols l 
Sequence symbols 1 
Variable symbols 1 


Length 1 
Name field symbol may appear 
more than once 3 
Previously defined 2 
Restrictions 3 | 
Symbol attribute reference 31-33 
Count (K') attribute 31. 
Defined (D') attribute 32. 
Integer (I') attribute 3l 
Length (L') attribute 3l 
Override in EQU instruction 15 
Number (N') attribute 31 
Scaling (S') attribute 31 
Type (T') attribute 31 
Symbolic linkages 8,12 
Symbolic parameter 
Format 26 
System macro 
Copied 23 
Definition 23 
Syntax errors in 23 
System variable symbols 45-46 
&SYSDATE 45 
&SYSLIST 45 
&SYSLOC 46 
&SYSNDX 
MHELP control on 44 
&SYSPARM 45-46 
&SYSTIME 45 


Terms | | 
Arithmetic combination of 1-2 
Number of 5 
Single 1-2 

TITLE instruction 18 


Type attribute 
Override, in EQU 15 


Unary operators 6-7 
USING instruction 8 


V-type constants 17 
Variable symbols 
Format 1 
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